Open API | Developer

Limiting the number of calls

For all the interfaces, there are limits on the number of calls within specific time frames. If these limits are exceeded, the HTTP status code 429 (too many requests) is returned.

A widget must be registered with an app session. The section Inter-app communication with app sessions for the identity provider app describes how to issue an app session.

warning: Authentication must take place with a bearer token in the authorization header. Authentication via cookie is not possible.

An app can register widgets only in the app’s own namespace.

You can introduce a new widget for your app as follows using the dashboard app.

Use an HTTP PATCH request for the path /dash/api/widget-registrations/<app-namespace>/<id>. Layout: [a-z-]/[a-z][a-z0-9]. The <id> part after the / must not exceed twelve characters. For example, acme-example/foobar.

Request

PATCH /dash/api/widget-registrations/<appname>/<widgetID>
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <AuthSessionId of an app session>

{
    "widget": {
        "type": "shortcut",
        "title": {
            "en": "My tasks",
            "de": "Meine Aufgaben"
        },
        "subtitle": {
            "en": "My open tasks",
            "de": "Meine offenen Aufgaben"
        },
        "icon": {
            "url": "https://example.com/tasks.svg"
        },
        "target": {
            "url": "/tasks/tasks?filter=foo"
        },
        "query": {
            "badge": {
              "url": "/tasks/tasks?type=badge"
            }
        }
    }
}

The dashboard app may return the following HTTP status codes:

Status code	Name	Meaning
200	OK	Registration or update of the widget was successful.
400		Widget registration object is invalid
401	Not authorized	Authentication via app session is required
403	Forbidden	A widget can be registered only within the internal widget namespace. Please ensure that the first part of the widget registration ID is the same as the app name.
429	Too many requests	Rate limit was reached.
5XX		An unexpected error occurred.

Property	Type	Requirement	Description
widget	Object	Yes	See Widget types for the layout
permissions	Object	No	See Permissions for the layout

Shortcut

Use this widget to enable the user to navigate to your app.

Property	Type	Requirement	Description
type	String	Yes	Value for the “shortcut” navigation widget
title	Object	Yes	See Language object
subtitle	Object	No	See Language object
icon.url	String	Yes	URL for an icon (SVG or PNG)
target.url	String	Yes	URL for the target address (if the target address is to be displayed with the old navigation behavior of d.ecs shell, specify the query parameter `oldBehavior=true` as well.)
query.badge.url	String	No	See “Query badge”
override_home_app_feature_id	String	No	If there is already a home app feature for the widget, this field can be used to overwrite this feature with the widget. This way, only one widget is displayed in the catalog. To do this, specify the ID of the home app feature. If an ID was specified when registering the home app feature, this can be used. Otherwise, the ID is made up of the URL that was specified in `features[].url`. All slashes are replaced by a minus sign. The ID is then composed as follows: `<APP_NAME>-<URL>`. For example, for the app `foobar` with the URL `/target/url`, the ID is `foobar-target-url`.

Layout of the query badge object

The following object must be delivered under the query.badge.url specified in the shortcut widget.

Property	Type	Requirement	Description
badge.count	Integer	Yes	If the value is greater than 0, a badge is displayed on the widget. Values greater than 99 are displayed as “99+”.

List

Use this widget to display a list widget.

Property	Type	Requirement	Description
type	String	Yes	Value for “list” list widget
title	Object	Yes	See Language object
subtitle	Object	No	See Language object
icon.url	String	Yes	URL for an icon (SVG or PNG)
target.url	String	Yes	URL for the target address (if the target address is to be displayed in the old shell, specify the query parameter `oldBehavior=true` as well.)
query.content.url	String	Yes	See List content
query.content.navigation	String	No	Navigation adopts the values `dapiNavigate`, `innerSupply` or `outerSupply`. If a value is unknown or undefined, `outerSupply` is used as the fallback.
footer.url	String	No	URL that is opened in the outer supply of the shell.
footer.label	Object	No	See Language object

IFrame

Use this widget to display external content via IFrame.

Property	Type	Requirement	Description
type	String	Yes	Value for the "iframe" IFrame widget
title	Object	Yes	See Language object
subtitle	Object	No	See Language object
icon.url	String	Yes	URL for an icon (SVG or PNG)
target.url	String	Yes	URL for the target address (if the target address is to be displayed in the old shell, specify the query parameter `oldBehavior=true` as well.)
size.min_w	Integer	No	Minimum width of the widget. Permitted values: 2 ≤ x ≤ 18
size.min_h	Integer	No	Minimum height of the widget. Permitted values: 2 ≤ x ≤ 16
source.url	String	Yes	URL for the HTML resource to be embedded in the IFrame. The URL must be an absolute path reference; that is, it must start with a leading slash `/` (for example, “/foobar/ressource.html” and not “foobar”)/ressource.html).
content_settings.url	String	No	URL for a configuration page for the IFrame content of the widget. The settings are saved for each widget instance. The URL must be an absolute path preference; that is, it must start with a leading slash `/` (for example, “/foobar/ressource.html” and not “foobar”/ressource.html). For more information about widget settings, see Widgeteinstellungen Javascript-API.
settings.url	String	No	DEPRECATED: This property is obsolete. Instead, please use the property `content_settings.url`. URL for a configuration page for the widget. The URL must be an absolute path reference; that is, it must start with a leading slash `/` (for example, “/foobar/ressource.html” and not “foobar”)/ressource.html).

Properties of the language object

Property	Type	Requirement	Description
Language tag	String	Specify at least one language.

List content

Your app must return the following JSON object under the URL specified for query.content.url.

For better time formatting a request to the url specified in query.content.url will contain a custom header x-dv-timezone. The value is the IANA Timezone Identifier, e.g. Europe/Berlin for german timezone.

Property	Type	Requirement	Description
entries	Array	Yes	Contains all the list entries. An entry object is specified for each entry.
line_variant	String	No	Defines the number of lines per element. If no value is defined, one line is displayed. For two lines, specify the value `twoline`.
leading_element_type	String	No	Defines the type of the leading element. You can choose between `icon` or `image`. If no value is specified, no element is displayed.
trailing_element_type	String	No	Defines the type of the trailing element. You can choose between `icon` or `caption`. If no value is specified, no element is displayed.

Entry object

Property	Type	Requirement	Description
title.text	String	Yes	Contains the title of the entry.
title.color	String	No	Defines the color of the title. Please specify the color as a hexadecimal value (for example, `#112233`).
subtitle.text	String	No	Contains the subtitle of the entry.
subtitle.color	String	No	Defines the color of the subtitle. Please specify the color as a hexadecimal value (for example, `#112233`).

fontMode	String	No	Defines the font for the text. You can choose between `bold` or `crossed-out`.
lead_element.material_icon	String	No	Defines the leading icon. The value must be a valid material icon. To use a material icon, set leading_element_type to `icon`.
lead_element.icon_color	String	No	Defines the color of the leading icon. Please specify the color as a hexadecimal value (for example, `#112233`).

lead_element.image_url	String	No	URL for an image (SVG or PNG). To use an image, set leading_element_type to `image`.
lead_element.image_size	String	No	Defines the size of the image. You can choose between `icon`, `avatar`, `medium` or `large`.
trail_element.material_icon	String	No	Defines the trailing icon. The value must be a valid material icon. To use an image, set trailing_element_type to `icon`.
trail_element.icon_color	String	No	Defines the color of the trailing icon. Please specify the color as a hexadecimal value (for example, `#112233`).

trail_element.caption	String	No	Contains the text to be displayed at the end of the entry. To use a caption, set trailing_element_type to `caption`.
trail_element.caption_color	String	No	Defines the color of the caption. Please specify the color as a hexadecimal value (for example, `#112233`).

target.url	String	No	URL that the entry forwards you to when clicked.

Permissions

You also have the option of specifying permissions for the widget. If you do not specify permissions, widgets are visible to all authenticated users. External users are excluded.

An OR link is used to check whether a user is permitted to view the widget; that is, at runtime, the system checks whether the user is in “group A” OR “group B” OR “group C”.

Layout

Property	Type	Requirement	Description
groups	Array	List of group objects

Group object

Property	Type	Requirement	Description
value	String	Yes	UUID (case-insensitive)

Example

{
    "widget": {
        //... Widget data
    },
    "permissions": {
        "groups": [
            {
                "value": "3E093BE5-CCCE-435D-99F8-544656B98681"
            }
        ]
    }
}

Limiting the number of calls

Registering a widget

Properties of the widget registration object

Supported widget types