Apis List

Usage

The Apis List component displays a paginated collection of available APIs within the Dev Portal. This component helps developers quickly browse and discover APIs offered by the Dev Portal. It includes built-in filtering and pagination controls to support scalable API catalogs and improve navigation across large sets of APIs.

Users can search for APIs by name, and the component supports both pre-defined filtering for displaying only a subset of APIs on specific pages, as well as end user filtering in the UI.

 ::apis-list
 ---
 cta-text: "View APIs"
 enable-search: true
 page-size: 3
 ---
 ::

To display only certain number of APIs without pagination, use the example below:

 ::apis-list
 ---
 cta-text: "Get started"
 page-size: 3
 pagination: false
 grid-columns-breakpoints:
  mobile: 3
  phablet: 3
  tablet: 3
  desktop: 3
 ---
 ::

API filtering

The Apis List component supports both pre-defined filtering for displaying only a subset of APIs on specific pages, as well as end user filtering in the UI.

The component utilizes the assigned attributes to filter the list of APIs retrieved and displayed by the component.

Pre-defined filters

Adding pre-defined filters on the Apis List component allows you to filter the APIs displayed based on specific attributes. This is useful for displaying only a subset of APIs on specific pages within your Dev Portal. The pre-defined filters are not editable by the end user and are not able to be cleared via the Filter UI.

To apply pre-defined filtering to the Apis List component, pass an object of attributes to the attributes prop. This will pre-filter the APIs displayed by the component by requesting only APIs that match the provided attributes from the Portal API.

For example, the following code will display only APIs that have the domain attribute set to Commerce or Flights, and the visibility attribute set to public.

::apis-list
---
attributes:
  domain:
    - "Commerce"
    - "Flights"
  # You can alternatively use inline array syntax.
  visibility: ["Partner"]
card-attribute-keys: ["domain"]
---
::

You can additionally choose to display the attributes on the API cards by using the card-attribute-keys prop. This will display the specified attributes key/value pairs on each API card, allowing users to see the attributes of each API at a glance.

Filter UI

To display an interactive filter alongside the list of APIs, set the show-filter prop to true. This will display the filter in the Dev Portal's left sidebar below any existing page-layout snippets, allowing users to filter APIs by attribute(s).

By default, all assigned attributes key/value pairs will be displayed in the filter UI.

::apis-list
---
enable-search: true
show-filter: true
filter-attribute-keys: ["domain", "visibility"]
card-attribute-keys: ["domain"]
---
::

To limit the attribute keys that are exposed to the filter, you can use the filter-attribute-keys prop to specify which attribute filters should be available.

If you also use a pre-defined filter (via the attributes prop), only the attribute values included in your pre-defined filter will be displayed under the corresponding attribute key in the filter UI.

Props

enableSearch

Enables searching APIs by name. When the prop is set to true, the search input is displayed above the APIs list.

• Type: boolean
• Default: false

showFilter

When the prop is set to true, the API filtering UI is displayed in the left sidebar below any existing sidebar snippets and allows users to manually filter the list of APIs.

When used alongside the attributes prop, the list will be pre-filtered to only include APIs that match the provided attributes.

• Type: boolean
• Default: false

attributes

Optionally provide a pre-defined object of API attributes to pre-filter the APIs displayed by the component.

• Type: Record<string, string[]>
• Default: {}

::apis-list
---
attributes:
  domain:
    - "Commerce"
    - "Flights"
  # You can alternatively use inline array syntax.
  visibility: ["Partner"]
---
::

cardAttributeKeys

An array of attribute keys to display on the API cards. If not provided, the component will not display any attributes on the API cards.

• Type: string[]
• Default: []

::apis-list
---
enable-search: true
show-filter: true
card-attribute-keys: ["domain"]
---
::

filterAttributeKeys

An array of attribute keys to display in the filter UI. If not provided, the component will not display any attributes in the filter UI.

• Type: string[]
• Default: []

::apis-list
---
enable-search: true
show-filter: true
card-attribute-keys:
  - "domain"
filter-attribute-keys:
  - "domain"
---
::

pagination

Enables pagination for the API List. When the prop is set to true, the pagination UI is displayed below the APIs List.

• Type: boolean
• Default: true

pageNumber

The current page number to display.

• Type: number
• Default: 1

persistPageNumber

When enabled, the API list page number will be persisted in the page URL query parameter.

Typically only desired when displaying a large list of paginated APIs.

• Type: boolean
• Default: false

pageSize

The number of entities per page.

• Type: number
• Default: 24

pageSizes

The pagination per-page options.

• Type: number[]
• Default: [24, 36, 48, 60]

ctaText

The call-to-action text to display on the API card's button.

• Type: string
• Default: View API

gridColumnsBreakpoints

Defines the number of columns to display for specific viewport widths.

Providing a column number for a given breakpoint will allow larger breakpoints to inherit the value if the number of columns is not explicitly defined for the larger breakpoint.

• Type: Breakpoints
• Default: { mobile: 2, phablet: 3, tablet: 3, desktop: 4, }

  /** Number of columns once the viewport width is greater than or equal to the breakpoint shown below. */
  interface Breakpoints {
    /** 640px */
    mobile?: number
    /** 768px */
    phablet?: number
    /** 1024px */
    tablet?: number
    /** 1280px */
    laptop?: number
    /** 1536px */
    desktop?: number
  }

Shared Props

This component also includes the shared props listed below:

• styles - default is ''.

See here for more information on shared props.

Slots

actions

Use the actions slot to add custom actions for the ApisCard component's header.

footer-left

Use the footer-left slot to overwrite the default button for the ApisCard component.