Home-APP

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
    }
  }
}

EigenschaftTypBeschreibungPflicht
_linksObjektLinkrelationen zu den Ressourcen einer AppJa
_links.featuresdescriptionObjektObjekt, welches den Pfad zu den angebotenen Features einer App enthältJa
_links.featuresdescription.hrefStringPfad, unter welcher die Features der App abgerufen werden sollenJa

Hinweis

Beachte auch weitere Informationen zum Aufbau der _links-Eigenschaft.

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": [
    {
      "url": string,
      "title": string,
      "subtitle": string,
      "iconURI": string,
      "summary": string,
      "description": string,
      "color": string
    }
  ]
}

EigenschaftTypBeschreibungPflichtAnmerkung
features[]ListeFeatures enthält ein oder mehrere Feature-Objekte.Ja
features[].urlStringEnthält die URL, zu der beim Klick auf diese Kachel navigiert werden soll.Ja
features[].titleStringEnthält die Überschrift der Kachel.Ja
features[].subtitleStringEnthält die Unterüberschrift der Kachel.Ja
features[].iconURIStringEnthält die URL zum Icon der App.JaURL zu einem Icon mit der Größe 32 x 32 Pixel im PNG- oder SVG-Format.
features[].summaryStringEnthält eine kurze Zusammenfassung der Funktionalität.Ja
features[].descriptionStringEnthält die Beschreibung, die beim Darüberfahren mit dem Mauszeiger der Kachel angezeigt wird.Nein, optional
features[].colorStringGibt die Hintergrundfarbe der Kachel an.JaAngabe hexadezimal im Langformat #aabbcc oder Kurzformat #abc.

Hinweis

Die Vordergrund- und Textfarbe der Kachel wird automatisch berechnet. Dabei kann es vorkommen, dass für ähnliche Farben unterschiedliche Vordergrundfarben ermittelt werden.

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"
    }
  ]
}

 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"
    }
  ]
}

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

Hinweis

Wegen des Cache-Verhaltens der Home-App kann es einen Moment dauern, bis die Kachel angezeigt wird.