Home-APP

Home API

 Functionality of the Home app

The Home app is the central HTTP interface for providing features on the start screen in the d.3ecm environment.

 Using the API functions

The information below explains how you can use the programming interface of the Home app for your own developments.

 Providing features

You can use this function to provide features (tiles) that are displayed by the Home app on the home page.

The following requirements must be met in order for the features of your app to be displayed on the home page:

  • The app must be registered on the http gateway app (on-premises only).
  • The app must deliver a link relation (featuresdescription) to the features.
  • The app must describe and deliver features using the feature object.

Note

The Home app sends the current user session with all requests to your app. This is done via the Authorization header and a bearer token. See also the API documentation Identity Provider app for more information.

 Delivering a link relation (featuresdescription) to the features

In order for the Home app to display the features of your app, your app must deliver a featuresdescription link relation at the base address to a GET request with the requirement header "Accept: application/hal+json".

Representation of the resource:


{
 "_links": {
 "featuresdescription": {
 "href": string
 }
 }
}
PropertyTypeDescriptionRequirement
_linksObjectLink relations to the resources in an appYes
_links.featuresdescriptionObjectObject that contains the path to the features offered by an appYes
_links.featuresdescription.hrefStringPath from which the features of the app are to be calledYes

Note

You can also read further information on the structure of the _links property.

Below is an example of such a response in JSON format:


{
 "_links": {
 "featuresdescription": {
 "href": "/exampleapp/features"
 }
 }
}

 Description of the features object

Under the URL href, a JSON object with the following details must be delivered to a GET request with the requirement header "Accept: application/hal+json".

Representation of the resource:


{
 "features": [
 {
 "id": string,
 "url": string,
 "title": string,
 "subtitle": string,
 "iconURI": string,
 "summary": string,
 "description": string,
 "color": string
 }
 ]
}
PropertyTypeDescriptionRequirementComment
features[]ListFeatures contains one or more feature objects.Yes
features[].idstringUnique id of this tile.No
features[].urlStringContains the URL to be navigated to when this tile is clicked.Yes
features[].titleStringContains the title of the tile.Yes
features[].subtitleStringContains the subtitle of the tile.Yes
features[].iconURIStringContains the URL for the app icon.YesURL for an icon, which is 32 x 32 pixels in size, in PNG or SVG format.
features[].summaryStringContains a brief summary of the functionality.Yes
features[].descriptionStringContains the description that is displayed when the user hovers over the tile with the cursor.No, optional
features[].colorStringSpecifies the background color of the tile.YesHexadecimal specification in long format #aabbcc or short format #abc.

Note

The foreground/text color of the tile is calculated automatically, it can happen that different foreground colors are determined for similar colors.

Below is an example of a features object with a feature.


{
 "features": [
 {
 "url": "/exampleapp/awesomefeature",
 "title": "Awesome Feature",
 "subtitle": "subtitle of feature tile",
 "iconURI": "/exampleapp/path/to/icon-thumbsup.png",
 "summary": "short summary of feature functionality",
 "description": "longer description of feature functionality, will be shown on tile hover",
 "color": "#ccc"
 }
 ]
}

 Example application

Imagine you are the developer of a fictitious feedback app. You want to provide a tile on the app’s home page.

The base address is https://example.com and the feedback app can be accessed at https://example.com/feedback/.

The home app sends a GET request to the feedback app at https://example.com/feedback/:

Example request


GET /feedback/ HTTP/1.1
Host: example.com
Accept: application/hal+json

The feedback app responds with the following example answer:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/hal+json

{
 "_links": {
 "featuresdescription": {
 "href": "/feedback/features"
 }
 }
}

The Home app now sends a second request to the feedback app with the URL https://example.com/feedback/features.


GET /feedback/features
Host: example.com
Accept: application/hal+json

The feedback app responds with the following example answer, which contains a feature:


HTTP/1.1 200 OK
Content-Type: application/hal+json

{
 "features": [
 {
 "url": "/exampleapp/awesomefeature",
 "title": "Awesome Feature",
 "subtitle": "subtitle of feature tile",
 "iconURI": "/exampleapp/icons/thumbsup.png",
 "summary": "short summary of feature functionality",
 "description": "longer description of feature functionality, will be shown on tile hover",
 "color": "#ccc"
 }
 ]
}

The feature of the feedback app is now displayed as a tile on the home screen together with features of other apps.

Note

Due to the cache behavior of the Home app, it may take a short while for the tile to be displayed.