Einleitung

Manchmal ist es notwendig und sinnvoll das Systeme Daten untereinander austauschen. Dadurch lassen sich Prozesse optimieren und automatisieren, manueller Aufwand verringern oder gar eliminieren, und somit auch die damit verbundenen Fehlerquellen.

Ein typisches Anwendungsbeispiel ist z. B. die Integration mit einem Web-CMS, um Beiträge oder Veranstaltungen die auf der Webseite veröffentlicht werden auch automatisch in App zu veröffentlichen. Oder die Einbindung von Informationsdiensten, die ihre Texte und Bilder automatisch an appdinx übergeben und so z. B. Beiträge, Veranstaltungen oder Galerien anlegen.

Für diesen Datenaustausch stellt appdinx eine REST-API zur Verfügung. Diese wird über einen umgebungsabhängigen Sicherheitsschlüssel abgesichert. Für die Anbindung und Nutzung der REST-API sind Programmierkenntnisse erforderlich.

Authentifizierung

Die Nutzung der REST-API erfordert einen API-Schlüssel, der im Inhaltsmanager der jeweiligen Umgebung generiert und aktiv geschaltet werden kann. Dieser API-Schlüssel muss in allen Anfragen als Parameter mitgegeben werden.

Dazu kannst du im Inhaltsmanager unter Einstellungen > Add-ons das Add-on „Programmierschnittstelle (API)“ aktivieren. Anschließend findest du die Konfiguration im Inhaltsmanager unter Einstellungen > Programmierschnittstelle (API). Kopiere den Sicherheitsschlüssel für die Anfragen.

Anfragen

Das REST-Paradigma wird in der Praxis bevorzugt per HTTP/S realisiert. Services werden per URL/URI angesprochen. Die HTTP-Methoden (GET, POST, PUT,…) geben an, welche Operation ein Dienst ausführen soll.

• GET – Fordert Daten vom Server an
• POST – Übermittelt Daten an den Server
• PUT/PATCH – Ändert bestehende Daten auf dem Server
• DELETE – Löscht bestehende Daten auf dem Server

Beispiel Anfrage

<method> https://<host-url>/<identifier>/<content>/api/<entityId>?apiKey=<apikey>

GET https://eu1.appdinx.com/abcdefghi/channels/api/?apiKey=hgfgjsgf234fgsgbehc

• <method> – Angabe der HTTP-Methode (GET, POST, PUT,…)
• <host-url> – Adresse zum Server, zum Beispiel eu1.appdinx.com, eu2.appdinx.com, etc.
• <identifier> – Deployment-ID (zu finden im Inhaltsmanager)
• <content> – Der Inhalt der angesprochen wird, siehe Endpunkte weiter unten
• <entityId> – Die Datenbank-ID wird beim Aktualisieren oder Löschen von Inhalten benötigt, siehe weiter unten
• <apikey> – Sicherheitsschlüsel aus dem Inhaltsmanager

Einige Anfragen erwarten ein FormData-Objekt als Body-Parameter, welches das einfache Erstellen eines Objektes ermöglicht. Dieses besteht aus Schlüssel/Werte-Paaren, welche Formular-Felder und ihre Werte repräsentieren.

Beispiel JavaScript

var formData = new FormData();

formData.append("title", "REST API");
formData.append("subtitle", "Ein Beispiel");
...

//Abschicken
var request = new XMLHttpRequest();
request.open("POST","https://eu1.appdinx.com/abcdefghi/articles/api/?apiKey=hgfgjsgf234fgsgbehc");
request.send(formData);

JSON API

Andere Endpunkte erwarten ein JSON-Objekt als Body-Parameter. Diese Endpunkte enden immer mit /json/.

Beispiel

var article={
  "author": "Max Muster“,
  "channels": [
    "1"
  ],
  "published": "true",
  "showAuthor": "true",
  "showPublishingDate": "true",
  "text": „Ein Text erstellt via JSON “,
  "title": "JSON API“",
  "top": false,
  "..."
}

//Abschicken
var request = new XMLHttpRequest();
request.open("POST","https://eu1.appdinx.com/abcdefghi/articles/api/?apiKey=hgfgjsgf234fgsgbehc");
request.setRequestHeader('Content-Type', 'application/json');
request.send(JSON.stringify(article));

Antworten

Zu jeder Antwort gibt es immer einen HTTP-Statuscode. Bevor die Antwort angesehen wird, sollte überprüft werden ob der Statuscode dem erwarteten Wert entspricht. Wenn eine Antwort erfolgreich ist, wird ein HTTP-Statuscode im Bereich 200 oder 300 zurückgegeben.

• 200 Ok
• 400 Bad Request
• 401 Unauthorized
• 404 Not Found
• 500 Internal Server Error

Beispiel Antwort

Status: 200 Ok

{
"id":1,
"name": "Allgemein",
"description":"Eine Beschreibung.",
"active": true,
"..."
},
{
"id":2,
"name": "Angebote",
"description":"Eine Beschreibung.",
"active": true,
"..."
}

Endpunkte

Die aktuellen Endpunkte findest du in deiner Umgebung unter Einstellungen > Programmierschnittstelle (API) oben/rechts über das -Symbol. Oder du gibst den folgenden Link im Browser ein:

https://<host-url>/<identifier>/swagger-ui.html