RESTful Api (join-restful)

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

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

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

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

Beispiel-Response

{
    "body": {
		shopArticleSku": "00001",
        "name": "Visitenkarte allgemein",    
	},
    "code": 0,
    "message": "",
    "extra": []
}

Die Schnittstelle antwortet mit folgenden HTTP-Status-Codes:

HTTP-Status-Code	Verwendungszweck

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

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