Home-APP

 Funktionsumfang der Home-App

Die Home-App ist die zentrale HTTP-Schnittstelle zum Bereitstellen von Features auf dem Startbildschirm in der d.3ecm-Umgebung.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der Home-App für eigene Entwicklungen nutzen kannst.

 Bereitstellen von Features

Mit dieser Funktion kannst du Features (Kacheln) bereitstellen, die durch die Home-App auf der Startseite dargestellt werden.

Folgende Anforderungen müssen erfüllt sein, damit die Features deiner App auf der Startseite angezeigt werden:

• Die App muss an der http gateway-App registriert sein (nur On-Premises).
• Die App muss eine Linkrelation (featuresdescription) zu den Features ausliefern.
• Die App muss Features mithilfe des Feature-Objekts beschreiben und ausliefern.

 Linkrelation (featuresdescription) zu den Features ausliefern

Damit die Home-App die Features deiner App anzeigt, muss deine App unter der Basisadresse auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" eine Linkrelation featuresdescription ausliefern.

Repräsentation der Ressource:

{
  "_links": {
    "featuresdescription": {
      "href": string
    }
  }
}

Nachfolgend findest du ein Beispiel für eine solche Antwort im JSON-Format:

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

 Beschreibung des Features-Objekts

Unter der URL href muss auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausgeliefert werden.

Repräsentation der Ressource:

{
  "features": [
    {
      "id": string,
      "url": string,
      "title": string,
      "subtitle": string,
      "iconURI": string,
      "summary": string,
      "description": string,
      "color": string,
      "badge": object
    }
  ]
}

Nachfolgend ist ein Beispiel für ein Features-Objekt mit einem 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",
      "badge": {
        "count": 3
      }
    }
  ]
}

 Beispielanwendung

Angenommen, du bist Entwickler einer fiktiven Feedback-App. Du möchtest für die App eine Kachel auf der Startseite bereitstellen.

Die Basisadresse ist https://example.com und die Feedback-App ist unter https://example.com/feedback/ erreichbar.

Die Home-App stellt eine GET-Anfrage an die Feedback-App auf https://example.com/feedback/:

Beispielanfrage

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

Die Feedback-App antwortet darauf mit folgender Beispielantwort:

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

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

Die Home-App stellt nun eine zweite Anfrage an die Feedback-App mit der URL https://example.com/feedback/features.

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

Die Feedback-App antwortet mit folgender Beispielantwort, welche ein Feature enthält:

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",
      "badge": {
        "count": 3
      }
    }
  ]
}

Das Feature der Feedback-App wird nun als Kachel zusammen mit Features weiterer Apps auf dem Startbildschirm angezeigt.