API (Application Programming Interface) ermöglicht es den Kunden, FMS mit ihrem System zu integrieren und Daten von verschiedenen Einheiten zu beziehen und an diese weiterzugeben.
Der Kunde stellt HTTP-Anfragen an das System, die Informationen über die beabsichtigte Aktion bieten. HTTP-Befehle die üblicherweise in einer API benutzt werden:
- GET – Quelle lesen;
- POST– Quellenstatus ändern;
Der angeforderte Inhalt wird im JSON-Format mit UTF-8-Kodierung bereitgestellt. Wenn ein anderes Format benutzt wird, wird dies in der Methodenbeschreibung festgelegt.
Der HTTP-Statuscode erkennt den Status der Anfrage – für erfolgreiche Anfragen wird der Statuscode200 ausgegeben. Zusammen mit dieser Antwort erhält man die vom Server angeforderten Informationen. Die Antworten werden sich je nach Art der verwendeten API unterscheiden. API-Antworten für unterschiedliche API-Typen werden in den entsprechenden Abschnitten beschrieben.
Wenn ein Fehler hinsichtlich der gesendeten Anfrage auftritt, wird das System eine Antwortnachricht mit einem Statuscode zurücksenden. Häufige Fehlercodes:
- Code 400 – Schlechte Anfrage – API-Anfrage wurde nicht erkannt.
- Code 401 – Nicht autorisiert – Dies bedeutet, dass die Authentifizierungsangaben fehlten oder falsch sind;
- Code 403 – Verboten – Dies bedeutet, dass der Kunde kein Recht hat, auf die angeforderte Quelle zuzugreifen oder die angeforderte Aktion durchzuführen;
- Code 404 – Nicht gefunden – Dies bedeutet, dass die angeforderte Quelle nicht gefunden wurde.
- Code 500 – Interner Serverfehler – bitte setzen Sie sich mit Ihren Tech-Support-Anbietern in Verbindung.
Fehlercodes bieten einige allgemeine Informationen über die Art des Fehlers und ermöglichen es dem Benutzer so, die Ursache des Problems herauszufinden.
Einige APIs verfügen über optionale Elemente (Parameter) in ihrer Antwort, optionale Parameter können vom System aus verschiedenen Gründen übersprungen werden (keine Daten, schlechte Daten, Antwort-Timeout usw.). Ein Benutzer darf nicht annehmen, dass bestimmte optionale Daten immer in einer Antwort enthalten sein werden.
API-Beschränkungen
Alle APIs haben eine einzige Beschränkung:
- Nicht mehr als 1000 Anfragen pro Minute.
Diese Beschränkung ist gültig für alle in FMS bestehenden APIs.
API-Authentifizierung
Die API-Authentifizierung und -autorisierung sind erforderlich, um die API-Verwendung für verschiedene Kunden und ihre Integration mit verschiedenen Systemen zu steuern. Um eine autorisierte Anfrage an System-APIs vorzunehmen, muss die Kundenanfrage zuerst einen API_key im Namen des Webbenutzers erhalten.
Kunden können einen API-Schlüssel nur durch direkte Kontaktaufnahme mit ihren Service-Anbietern für technischem Support erhalten. Der API-Schlüssel besteht aus zufällig erstellten Buchstaben, Zahlen und Symbolen.
Beispiel für eine Anfrage unter Verwendung eines API_key:
Wenn der API_key abgelaufen, entfernt oder einfach nur deaktiviert ist, wird das System die folgende Antworte geben:
API-Endpunkte, Anfrageparameter und Antworten können in „Swagger“ über den folgenden Ling vorab betrachtet werden: https://api.fm-track.com
Hinweis
Es ist immer erforderlich, eine API-Version in allen API-Arten festzulegen.
Wichtig!
Aufgrund der ständigen Entwicklung der API und des Systems, von dem die Informationen angefordert werden, können Benutzer manchmal Parameter erhalten, die nicht in den Beschreibungen aufgeführt sind. Es wird empfohlen, unbekannte Parameter, die nicht in jeder API-Beschreibung dokumentiert sind, zu ignorieren.
Versionierung und Kompatibilität
Die API-Lösung wird ständig aktualisiert, verbessert und anderweitig modifiziert. Daher ist es erforderlich, zu verstehen, was „Kompatibilität“ bedeutet und wie es, den Benutzer betrifft, wenn er die API-Lösung verwendet.
Wenn eine API aktualisiert wird, kann eine der folgenden beiden Optionen auftreten:
- Die umgekehrt kompatible API – das bedeutet, dass die vorgenommenen Veränderungen, den Arbeitsablauf der API in keiner Weise beeinflussen werden, so dass keine neue Version erstellt wird.
- Die API ist nicht umgekehrt kompatibel – das bedeutet, dass einige API-Komponenten geändert wurden, damit sie nicht mehr auf die gleiche Weise funktionieren wie zuvor. In diesem Fall, wird eine neue API-Version veröffentlicht.
Was wird als eine umgekehrt kompatible API-Version angesehen:
- Neue API-Quellen wurden hinzugefügt;
- Neue optionale Anfrageparameter wurden der bestehenden API hinzugefügt
- Neue Eigenschaften wurden zu den vorhandenen API-Antworten hinzugefügt.
- Die Reihenfolgen der Eigenschaften wurden in den bestehenden API-Antworten geändert.
- Die Veränderung der Länge oder des Formats der Objekt-IDs oder anderer undurchsichtigen Zeichenfolgen
Der Benutzer kann davon ausgehen, dass die vom System generierten Objekt-IDs nie länger als 255 Zeichen sind, aber er sollte in der Lage sein, IDs mit einer potenziellen Länge von 255 Zeichen zu handhaben. Wenn der Benutzer beispielsweise MySQL verwendet, sollten die IDs in einer VARCHAR(255) COLLATE utf8_bin-Spalte gespeichert werden (die COLLATE-Konfiguration gewährleistet die Unterscheidung zwischen Groß- und Kleinschreibung bei Suchen) - Hinzufügen neuer ENUM-Typen. – alle Systeme sollten unbekannte ENUM-Typen elegant behandeln. Wenn sich beispielsweise der Typ von [Privat, Geschäftlich] in [Privat, Arbeit, Geschäftlich] ändert, sollte das keine Auswirkungen auf das System haben.