api-card

Component description

The api-card component creates a list of cards that serve as easy navigation to apps, spaces, or objects on pages/dashboards.

Example

Minimal JSON

{
    "type": "api-card",
    "api": "",
    "nameAttribute": "",
    "layouts": []
}

{
    "key": "space_cards_app_overview",
    "template": {
        "componentId": "template#space_cards_app_overview",
        "type": "api-card",
        "api": "api/dashboard/spaces",
        "headerTitle": "page.home.spaces.title.key",
        "noDataText": "page.home.spaces.no_data.key",
        "noDataIconKey": "circle",
        "onClickOpens": "link",
        "nameAttribute": "#shortDescription",
        "middleSectionAttributeTypeKey": "#shortDescription",
        "bottomTextKey": "core#api.card.objects.apps",
        "filter": {
            "applicationId": {
                "value": "@appId"
            },
            "includeSubspaces": {
                "value": true
            }
        },
        "layouts": [
            {
                "type": "cards"
            }
        ]
    }
}

Example taken from the core package.

Nested properties

Property	Description	Values	Mandatory
`type`	api-card	string	Yes
`api`	API endpoint which provides data to the card. See the full list of available API endpoints.	string*	Yes
`layouts`	Default layout for the API cards. At least one must be selected. To enable a layout selector, add more layout types. Supported values are: cards, table	array of strings in (“cards”, “table”)	Yes
`nameAttribute`	Name of the card displayed as the first row. Supported values are for example: spaceName, applicationName, objectName, dashboardName, #shortDescription	string	Yes
`additionalRelationTypes`	Array of keys of additional relation types displayed on the card.	array	No
`additionalUserRelationTypes`	Array of keys of additional user relation types displayed on the card.	array	No
`bottomTextKey`	Key of the translation used at the bottom of the card. E.g., number of objects, apps, sub-spaces.	string	No
`componentId`	Unique ID of a component. If left empty, a random string will be generated. Primarily used in patch packages to define the component’s position within the layout (template).	string	No
`favouriteObjectTypes`	Array of keys of favorite object types.	array	No
`filter`	Conditions used to limit or refine data selection. For more information, see filter.	json	No
`headerRightActions`	Actions available in the component header. Supported values are: search, addSpace	string in (“search”, “addSpace”)	No
`headerTitle`	Translation key of the title. Define the key in translations to specify how the text is displayed in the UI. Unlike the `name` property, if you use a specific string of text for the title, this text will appear with the package key. For example, `Comment Section` will be displayed as `package_key_comment` section.	string	No
`headerTitleFiltered`	Assets filter.	string	No
`iconSource`	Configures the source of the card’s icon in the top-left corner. Replaces the deprecated icon behavior of numeric `secondaryNameAttribute` values. For more information, see iconSource.	json	No
`isMarketplaceVisual`	Shortens the middle section of long breadcrumbs into ellipses. A tooltip with the full path is available upon hover.	boolean	No
`middleSectionAttributeTypeKey`	Key of the translation used in the middle of the card. E.g., `#shortDescription` for description.	string	No
`noDataIconKey`	Key of the icon used to visually represent the asset. Use predefined icons from Settings > Configuration > Icons, or define custom ones in the icons asset. Icon is used when no object is found.	string	No
`noDataText`	Key of the translation displayed when no object is found.	string	No
`objectPathKey`	Object or application path. Supported value is: pathNames: Use to add object path to the card.	string	No
`onClickOpens`	Action when a card is clicked. Supported values are: link: Opens the specified link., newWindow: Opens the asset in a new window., rightPanelDetail: Opens the object in a right panel.	string in (“link”, “newWindow”, “rightPanelDetail”)	No
`relationTypeKey`	Key of the relation type displayed on the card.	string	No
`searchFormKey`	Key of the relevant search form.	string	No
`secondaryNameAttribute`	Key of the attribute used as the card’s gray subtitle text.	string	No
`sortTypes`	Parameters that can be used to sort API cards. Add multiple types for a selector. Supported values are: created, modified, name, popularity	array of strings in (“created”, “modified”, “name”, “popularity”)	No
`userRelationTypeKey`	Key of the user relation type displayed on the card.	string	No

Limitations

When searchFormKey is set, the frontend expects iconId in the API response. The backend does not currently return it, so object type icons are not displayed in this configuration.

Troubleshooting

To show an icon from a related entity in the top-left corner of each card, use iconSource with type: "relationTarget":

{
    "type": "api-card",
    "api": "api/dashboard/...",
    "nameAttribute": "name",
    "iconSource": {
        "type": "relationTarget",
        "relationTypeKey": "core_code_lists#has_area",
        "property": "application"
    }
}

The backend automatically includes the relation in the request — additionalRelationTypes is not required. When property is "application", the application name is also displayed as the card’s gray subtitle.

Warning

Earlier packages may use secondaryNameAttribute with a numeric string (e.g., "48") to configure the card icon via a relation type ID. This behavior is deprecated — migrate to iconSource with type: "relationTarget" and remove the numeric value from secondaryNameAttribute.