|
Spezifikationen |
  
|
|
Spezifikationen |
|
Beschreibung
Auf dieser Hilfe-Seite gibt Hinweise und Beispiele, wie mit der MERCATOR API kommuniziert werden kann.
Technische Übersicht
| • | Web API auf Basis von .NET |
| • | Datenbankzugriff über nativen SQLBase .NET Provider |
| • | HTTP Basic Authentication mit MERCATOR Benutzerdaten (Benutzername/Passwort) des anzusteuernden Mandanten |
| • | alle API Endpunkte erlauben einen Datenzugriff separat pro Mandant |
| • | Austauschformat JSON (JavaScript Object Notation) |
| • | lowerCamelCase und Englische Datenschlüssel für einen genormten und einheitlichen Zugriff |
URL Aufbau
Die MERCATOR API ist eine vollwertige REST API und ist dementsprechend auch so strukturiert und konzipiert.
Bei jeder Anfrage ist die Übergabe der Zugangsdaten notwendig, wobei folgende URL Struktur existiert:
http|https://[IP/URL]/api/[MANDANT]/[ENDPUNKT]/[ACTION|ID:optional]
| • | IP/URL = Adresse Ihres Servers, der Zugriff kann lokal im Intranet als auch extern per DynDNS/DDNS erfolgen |
| • | [MANDANT] = Name des Mandanten, der Daten liefern soll, z.B. mand001 |
| • | [ENDPUNKT] = Name des API Bereiches (werden in der Online-Hilfe unter Datenbereiche vollständig erklärt), z.B. customers |
| • | [ACTIONID:optional] = ID des anzusteuernden Datensatzes oder expliziter (aber allgemeiner) Unterbereich des Endpunktes (optional, nur bei der Abfrage von Detaildaten erforderlich) |
Optionale Filtermöglichkeiten pro Endpunkt können per GET Parameter erfolgen.
Weitere Infos und Doku innerhalb der Online-Hilfe bei den jeweils passenden Datenbereichen.
Autorisierung
API-Anmeldungen bzw. Autorisierungen erfolgen über die HTTP Basic Authentication (Teil des Standard HTTP Protokolls https://de.wikipedia.org/wiki/HTTP-Authentifizierung)
Die Anmeldedaten werden beim Zugriff über Ihren Browser per Standard-Dialog erfragt.
Die programmatische Übertragung dieser Anmeldeinformationen erfolgt über den Authorization header
Folgender Aufbau ist beim Zugriff per Header erforderlich:
| • | Benutzername und Passworz mit einem Doppelpunkt verknüpfen, z.B. Benutzername:Passwort |
| • | diese Kombination anschließend Base64 encoden |
| • | die Kombination aus Header und Zugangsdaten an jede API Anfrage übergeben, z.B. Authorization: QmVudXR6ZXJuYW1lOlBhc3N3b3Jk |
Basic Autorisierungen erfolgen generell nicht verschlüsselt, achten Sie daher auf eine gültige SSL Verbindung zu Ihrer API bzw. zu Ihrem Server!
Beachten Sie außerdem:
| • | API Anmeldungen prüfen die zulässige Anzahl an aktuellen Anmeldungen |
| • | API Benutzer können nicht während des Datenzugriffes bereits in MERCATOR angemeldet sein, achten Sie daher auf vorhandene und freie Benutzerkonten |
Autorisierungen (Benutzername/Passwort) beziehen sich immer auf anzusteuernden Mandanten.
Diese können wie in der Installations- Anleitung genannt auch explizit vom Zugang ausgeschlossen werden.
HTTP Status Codes
Die MERCATOR API antwortet auf Anfragen prinzipiell mit JSON formatierten Daten und einem gültigen HTTP Status Code.
Bei Fehlern gibt es neben konkreten Meldungen (kein JSON) noch passende Status Codes, um programmatisch bereits vor der eigentlichen Datenauswertung den Erfolg prüfen zu können:
Status Code |
Antwort |
Beschreibung |
200 |
JSON |
gültige Antwort der API |
401 |
Fehlende Autorisierung |
Die Anfrage erfolgte ohne Authorization Header |
401 |
Falsches Autorisierungsprotokoll |
Die Anfrage erfolgte nicht per Basic Authorization |
401 |
Fehlende Zugangsdaten |
Die Anfrage erfolgte ohne Benutzername und Passwort |
401 |
Mandant erforderlich |
Die Anfrage erfolgte ohne Mandanten (im Endpunkt) |
401 |
Mandant wird nicht unterstützt |
Der angesteuerte Mandant wurde vom Zugang ausgeschlossen |
401 |
Benutzer ist bereits angemeldet |
Der Benutzer ist bereits in MERCATOR angemeldet |
401 |
Falsche Zugangsdaten |
Die Autorisierung enthält falsche Zugangsdaten |
404 |
- |
kein gültiger Datensatz gefunden (bei Detailanfragen) |
500 |
Fehlermeldung |
Keine gültige Anfrage bzw. Antwort |