Grundlagen der Kommunikation, Authentifizierung

URL und Antwortformat

Die API-Schnittstelle ist unter folgender Adresse verfügbar:

https://api.wedos.as/partner/{method_name}

Anhand der requestId können wir im Problemfall die konkrete Kommunikation in den internen Logs auffinden.

Authentifizierung

Jede API-Anfrage muss authentifiziert sein. Dazu dient API-Schlüssel, der ähnlich wie ein Passwort funktioniert, aber ausschließlich für die API bestimmt ist.
Der API-Schlüssel ist nicht identisch mit dem Passwort, das Sie für die Anmeldung in der Partnerverwaltung verwenden.

HTTP-Header

Die Authentifizierung erfolgt mithilfe von zwei HTTP-Headern, die jeder Anfrage hinzugefügt werden müssen:

• X-Auth-Id – ID des API-Schlüssels
• X-Auth-Key – der API-Schlüssel selbst

Beispiel einer HTTPS-Anfrage

Nachfolgend ein Beispiel für eine einfache API-Anfrage einschließlich der erforderlichen HTTP-Header.
Es handelt sich um die Methode ping, mit der Sie überprüfen können, ob die Kommunikation korrekt funktioniert.

GET /partner/ping HTTP/1.1
Host: api.wedos.as
Accept: application/json
X-Auth-Id: KEYID
X-Auth-Key: YOURKEY

Beispielantwort

Bei einem erfolgreichen Aufruf der ping-Methode gibt die API die Partner-ID sowie das aktuelle Datum und die Uhrzeit zurück:

{
  "stamp": 1495544024,
  "time": "2017-05-23 14:53:44",
  "partnerId": 300000,
  "requestId": "1495544024.0084.8420"
}

Fehlerantworten

Im Fehlerfall gibt der Server einen anderen HTTP-Code zurück als 200 und im Antwortkörper werden der Fehlercode und dessen Beschreibung angegeben.
Zum Beispiel bei einer Anfrage mit fehlerhafter Authentifizierung:

{
  "error": {
    "code": "C507",
    "error": "Authentication failed"
  },
  "requestId": "1495544185.1615.8422"
}