Die RESTful API ist Domain-Sensitiv und über den Endpunkt /rest/v5 erreichbar.
Request
Parameter
Alle Parameter eines Requests müssen mit Content-Type application/x-www-form-urlencoded URL-kodiert übertragen werden.
Request-Methoden
Es werden 4 gängige HTTP-Request-Methoden verwendet:
Request-Typ | Verwendungszweck |
---|---|
GET | Datenholung |
POST | Datenanlage |
PUT | Datenmanipulation |
DELETE | Datenlöschung |
Request-Header
Mit Ausnahme der Authentifizierungs-Anfrage muss jeder Request einen Autorisierungs-Header Authorization enthalten, der den zuvor abgeholten Zugriffstoken enthält.
Mehr dazu hier.
Aufbau
Eine RESTful-Ressource setzt sich aus folgenden Teilen zusammen:
- Protokoll
- Hostname (Domain)
- Schlüsselwort für den RESTful-Endpunkt
- Schnittstellen-Version
- Ressourcen-Endpunkt
Beispiel: http://www.meinedomain.com/rest/v5/accessToken
Services
- Datensätze einer Tabelle (List)
- Eltern eines Datensatzes (Parents)
- Karte eines Datensatzes (Card)
- Kinder eines Datensatzes (Children)
Rückgabewerte
Die Response erfolgt immer im JSON-Format mit Content-Type application/json und Charset UTF-8 und enthält folgende Keys:
Key | Inhalt | Datentyp |
---|---|---|
body | Die angefragten Inhalte | Array/Objekt |
code | 0 bei Erfolgt, 1 im Fehlerfall | Integer |
message | Eine Erfolgs- oder Fehlermeldung | String |
extra | Zusätzliche Informationen zu Fehlern oder Inhalten | Array |
{ "body": { shopArticleSku": "00001", "name": "Visitenkarte allgemein", }, "code": 0, "message": "", "extra": [] }
Die Schnittstelle antwortet mit folgenden HTTP-Status-Codes:
HTTP-Status-Code | Verwendungszweck |
---|---|
200 | Erfolgreicher Request |
401 | Fehlerhafte Authentifizierungs- oder Autorisierungsanfrage oder abgelaufener Zugriffstoken |
403 | Fehlende Rechte zum Ausführen der Anfrage |
404 | Nicht existente Ressource oder fehlende Pflichtparameter |
405 | Falscher Request-Typ für die angefragte Ressource |
500 | Fehler auf Serverseite |
Fehler-Codes: Im Fehlerfall wird in message eine Fehlermeldung mit Fehlercode zurückgegeben:
Code | Beschreibung |
---|---|
100 | Api ist deaktiviert |
101 | Nicht existente Ressource oder fehlende Pflichtparameter |
102 | Fehlerhafte Konfiguration der REST-Page |
103 | Fehlende Pflichtparameter für die aufgerufene Ressource |
104 | Request-Typ existiert für die aufgerufene Ressource nicht |
105 | Die Rolle des ausführenden Benutzers hat nicht die Rechte, die angeforderte Ressource zu verarbeiten |
106 | Ungültiger Request-Typ |
107 | Ungültige Filterkonfiguration der REST-Page |
108 | Ein oder mehrere Einschränkungen der aufgerufenen Ressource wurden nicht erfüllt |
109 | Ungültige Locale |
110 | Locale in Verbindung mit Übersetzungen nicht erlaubt |
111 | Fehler bei Authentifizierung oder Autorisierung mittels OAuth2 |