REST-API

Die REST-API von CONTAILOR bildet eine Webschnittstelle für die Funktionalität des CMS, die von den Projekten und damit auch den Shops verwendet werden kann.

Funktionen der REST-API können per HTTP-Request über den Browser oder andere Tools (wie z.B. Postman) abgesendet werden. Diese Webschnittstelle unterliegt einigen Sicherheitsmechanismen und muss erst im Backend aktiviert werden.

Aktivieren

Um die REST-API nutzen zu können müssen im Backend einige Einstellungen getroffen werden.
Grunsätzlich muss unter "Allgemeine Einstellungen > API > REST-API erlauben" angehakt werden. Davor kann keine der Funktionen genutzt werden. Werden auch inhaltsändernde Funktionen (z.B. Elemente anlegen, etc.) benötigt, dann muss zusätzlich auf der gleichen Backend-Seite Inhaltsänderungen über die API erlauben angehakt sein. Soll auch eine Benutzerverwaltung möglich sein, muss zudem der Haken bei Benutzerverwaltung über die API erlauben aktiv sein.

Da REST-APIs per Web eine Angriffsoberfläche bieten, sollte nach Möglichkeit auf bestimmte IPs eingeschränkt werden, sodass nur diese Zugriff haben. Dies kann mit der Einstellung REST-API auf IPs einschränken erfolgen. Details wie diese anzugeben sind siehe bei der Beschreibung der Einstellung.

Authentifizierung

Die Authentifizierung funktioniert nach dem Prinzip von OAuth 2.
Zunächst wird mit einem Aufruf von <Instanzurl>/contailor/api/v2/manager/gettoken ein Token angefordert, der zur Verwendung der API authorisiert. Diesem Aufruf wird ein Benutzer-Identifikator (Parameter Username) und ein Passwort (Parameter Password) mitgegeben. Für den Identifikator des Benutzers kann je nach eingestelltem Authentifizierungsmodus (siehe Einstellung Einloggen von Benutzern) ein Benutzername und/oder die E-Mail-Adresse verwendet werden. Die Antwort enthält im Erfolgsfall ein Json-Objekt mit einem Token (.access_token) und den Status (.status) "LoggedIn". Alle möglichen Statuswerte beim Login siehe unter LoginState.
Es können sich nur Benutzer an der REST-API anmelden, keine Administratoren.

Beim Aufrufen weiterer Funktionen muss nun der von oben beschriebener Funktion zurückgegebene Token immer mitgegeben werden, um die Identität des angemeldeten Benutzers klarzustellen.

Die Gültigkeit des Tokens liegt aktuell bei so vielen Minuten wie in der Session-Timeout in der Sitzungsverwaltung hinterlegte Wert. Jeder Request mit einem Token über die REST-API verlängert die Gültigkeit des Tokens um den selben Betrag.

Zudem zu beachten ist wie bei allen Funktionen, dass der angemeldete Benutzer auch die erforderlichen Rechte für die Aktion haben muss. Ist dies nicht der Fall wird ein entsprechender Status gesendet.

Verwendung

Die über die REST-API zur Verfügung stehenden Methoden sind im Großen und Ganzen die gleichen wie die, die über die "normale", also serverseitige API angesprochen werden können mit folgenden Unterschieden:

Die Abfrage von einzelnen Propertys wird nicht separat unterstützt, da in den Antworten der REST-API zu jedem Objekt die Grundparameter automatisch vorliegen
Die REST-Schnittstelle kann nur textbasiert arbeiten, d.h. Funktionen, die in der serverseitigen API nicht shared sind und/oder Objekte per Parameter bekommen, haben in der REST-API dann jeweils einen Namen oder eine ID um das betreffende Objekt identifizieren zu können.
Bestimmte sicherheitsrelavente Funktionen wie Passwort ändern oder solche, die schlicht (noch) nicht benötigt werden sind ggf. nicht in der REST-API enthalten, diese befindet sich noch im Aufbau

Die URL um die Funktionen anzusprechen lautet:

<Instanzurl>/contailor/api/v2/<Controllername>/<Funktionsname>

Dabei entspricht <Instanzurl> der URL der jeweiligen Website, also z.B. https://hilfe.contailor.de. Der darauffolgende Teil ist fest, dann folgt mit dem Controllernamen der "Bereich", der angesprochen wird. Das ist jeweils die Bezeichnung der Entität auf der man arbeitet, also z.B. page oder shape. Schließlich folgt der Funktionsname, z.B. getbyid.

Die REST-API unterstützt wie die pflegbaren Seiten von CONTAILOR selbst auch den EditMode. Dieser kann durch Anhängen des Parameters
"?edit" an die REST-URL abgefragt werden. Zu beachten ist, dass manche Funktionen nur im EditMode zugelassen sein können. Ohne den Parameter wird der veröffentlichte Zustand betrachtet.

Beispiel:

Möchte man die Eigenschaften der Seite mit der ID 1 im EditMode erhalten, würde der Aufruf hier in der CONTAILOR-Hilfe wie folgt lauten:

https://hilfe.contailor.de/contailor/api/v2/page/getbyid?edit

Die ID 1 wird als Parameter oder als Form-Data-Wert übergeben. Ebenso muss wie bereits erwähnt immer der Authentifizierungstoken als Authorization-Wert mitgegeben werden.

Struktur der Antworten

Was bei den einzelnen REST-Funktionen zu beachten ist und welche Funktionen per REST-API angesprochen werden können ist bei den jeweiligen Funktionen im Bereich Server beschrieben.
Der Umfang der Antworten, also welche Eigenschaften von welcher Entität per REST-API herausgegeben wird findet sich unter Result.

Die Antworten der REST-API sind immer Json-Objekte. Diese bestehen aus einem Wert status und einem Wert result.
Im Status steht der Rückgabestatus des gesamten Aufrufs. Die einzelnen möglichen Werte sind unter dem Enum ApiStatus beschrieben. Hiermit kann v.a. auf unerwartete Fehler-Status reagiert werden.
Parallel dazu gibt es den Wert Result, in diesem steht der Rückgabewert der eigentlichen Funktion, dieser kann je nach Funktion eine beliebige Komplexität haben und bei inhaltsändernden Funktionen wird hierin wieder ein Wert status vorkommen, der den Status der Aktion selbst darstellt.

Zusammengefasst sieht eine solche Antwort von page/getbyid also z.B. so aus:

Copy

{

"status": "ok",

"result": {

"page": {

"ID": 1,

"Name": "Startseite",

"Title": "Startseite - CONTAILOR-Hilfe",

...

}

Anwendungsbeispiel

Das folgende Beispiel zeigt, wie man sich mit einer Funktion GetToken einen Token holen kann und dann mit GetPage den obenstehenden Result-Wert eines Page.GetByID-REST-Aufrufs erhalten kann. Im Beispiel wird dieser in eine separat definierte Klasse "PageResult" gelegt, die alle Werte enthält.

Copy

private string GetToken()
       {
           using (WebClient HttpClient = new WebClient())
           {
               string CallURL = _ApiBaseURL + "https://contailor.local/contailor/api/v2/manager/gettoken";
               NameValueCollection ReqParm = new NameValueCollection
               {
                   { "Username", "myuseremail@mydomain.com" },
                   { "Password", "*****" }
               };

               ConcurrentDictionary<string, string> Response = new ConcurrentDictionary<string, string>();
               try
               {
                   Response = JsonConvert.DeserializeObject<ConcurrentDictionary<string, string>>(
                   new UTF8Encoding().GetString(HttpClient.UploadValues(CallURL, "POST", ReqParm))
               );
               }
               catch (WebException Ex)
               {
                   // Exceptions behandeln
               }
               Response.TryGetValue("access_token", out string Token);

               return Token;
           }
       }

Copy

public PageResult GetPage()
       {
           PageResult ResultObject = new PageResult();
           string Token = GetToken();

           using (WebClient HttpClient = new WebClient())
           {
               HttpClient.Headers.Add("Authorization", Token);

               NameValueCollection ReqParm = new NameValueCollection
               {
                   { "PageID", "1" }
               };

               try
               {
                   ResultObject = JsonConvert.DeserializeObject<PageResult>(new UTF8Encoding().GetString(
                       HttpClient.UploadValues(
                           "https://contailor.local/contailor/api/v2/page/getbyid",
                           "POST",
                           ReqParm
                       )
                   ));
               }
               catch (WebException ex)
               {
                   // Exceptions behandeln
               }
           }

return ResultObject;
}

War dieser Beitrag hilfreich?

11 von 11 fanden dies hilfreich.

Schade! Bitte teilen Sie uns doch mit was Ihnen nicht weitergeholfen hat.

Es ist ein technisches Problem aufgetreten. Bitte wenden Sie sich telefonisch oder per E-Mail an uns.