v.Api – Designprinzipen
Inhalt
- Einführung
- Einheitliche Code-Basis
- Moderne REST-Api
- Dokumentation über OpenAPI und Swagger
- Authentifizierung über JSON Web Token
- API Versionierung
- Abbildung von v.Soft Funktionen
1. Einführung v.Api
Die v.Api ist eine REST-Programmschnittstelle und stellt eine Erweiterung von v.Soft dar. Die v.Api dient hauptsächlich als Kommunikationsschnittstelle zur v.App und wurde dementsprechend von uns gestaltet. Die v.Api ist aber auch als Schnittstelle für Administratoren von Firmen die v.Soft im Einsatz haben gedacht, die auf sichere Art und Weise Daten von v.Soft abrufen und ggf. verändern möchten.
2. Einheitliche Code-Basis zwischen v.Soft und der v.Api
Zwischen v.Soft und der v.Api gibt es eine geteilte Code-Basis, d.h. der Programmcode wird zu gewissen Teilen von beiden System benutzt. Sowohl v.Soft als auch die v.Api (und auch der v.Soft Dienst) liegen im gleichen Programmverzeichniss (normalerweise C:\Vepos\vSoft) und greifen hier auf die selben Programmdateien (*.dll) zu. Die Vorteile dieser Einheitlichen Codebasis sind:
- Fehlerquellen werden vermieden
- Es gibt keinen doppelten Code oder Projekte
- Wartung und Updates werden vereinfacht
- Neue Funktionen können leichter in die v.Api übernommen werden
3. Moderne REST-Api
Für die neue v.Api haben wir uns für eine moderne REST-Api entschieden, wie sie heute bei vielen Systemen, Projekten und Apps Standard ist.
Designprinzipen einer REST-Api
REST – Representational State Transfer
Bezeichnet den Übergang einer Anwendung von einem Status in den nächsten. Der Benutzer kann durch das Ansteuern einzelner URLs in Verbindung mit HTTP Methoden den Status der Anwendung abfragen oder in den nächsten Status wechseln.
Client-Server Architektur
Der Server (die Api) stellt einen oder mehrere Dienste bereit. Die Dienste können bei Bedarf von den Clients abgerufen werden
Statelessness (Zustandslosigkeit)
Der Api speichert keine Informationen zwischen zwei Anfragen einen Clients zwischen. Jede Anfrage an die Api muss alle Informationen enthalten, die zum Bearbeiten der Anforderung notwendig sind. Zwischengespeichert wird einzig und allein der Zustand der Anwendung (via Datenbank), diesen kann der Client abfragen.
Adressierbarkeit der Ressourcen und Parameter
Jede Ressource der Api wird durch eine eindeutige URL repräsentiert. Die Urls sind sprechend formuliert, d.h. bereits an der URL ist sichtbar welche Ressource identifiziert wird. Parameter, die die Ressource nicht identifiziert, werden also Optionale Parameter angehängt.
Die v.Api baut stark auf sprechende Http-Verben und Routen auf.
HTTP-Verben
Über HTTP Methoden und deren Verben wird bereits beim Aufruf ersichtlich, was mit der Ressource passieren soll. Zusätzlich zeigt das HTTP Verb an, ob eine Methode Safe (Ressource ändert sich nicht) und/oder Idempotent (Die Methode kann mehrfach hintereinander aufgerufen, Ressource bleibt gleich) ist.
Typisches Verhalten der HTTP-Verben in der v.Api
HTTP-Statuscodes
Die Api antwortet grundsätzlich mit HTTP-Statuscodes.
4. Dokumentation über OpenAPI/Swagger
Die Dokumentation der v.Api erfolgt grundsätzlich über den OpenAPI Standard via Swagger. Die OpenAPI Spezifikation ist ein Standard für maschinenlesbare Dateien (JSON), welche REST-konforme APIs beschreiben und dokumentieren. Die OpenAPI Dokumenation bietet:
- Ein Verzeichniss aller zur Verfügung stehender Funktionen
- Deren Parameter und Rückgabewerte (HTTP-Status)
- Übersicht über die verwendeten Datenstrukturen (Schemas)
- Erlaubt Kommentare und Funktionsbeschreibungen
Automatische Erzeugung
Die v.Api liefert ihre eigene Dokumentation von Haus aus mit. Die OpenAPI-Dokumentation wird automatisch durch den Webserver erzeugt und aktualisiert sich damit auch von selbst. OpenAPI lässt sich dadurch auch gut in Tools wie Postman o.Ä. integrieren.
Testumgebung und Visualisierung via Swagger
Über Swagger wird die automatisch generierte Dokumentation visualisiert und in Funktionen gruppiert. Swagger stellt dann auch automatisch eine Testumgebung zur Verfügung, über die sich die einzelnen Funktionen der API direkt aufrufen lassen.
Mit Swagger erhälst du automatisch eine vollständige Dokumentation der Api und kannst Funktionen sofort testen
5. Authentifizierung via JSON Web Tokens (JWT)
Die Benutzer-Authentifizierung wird bei der v.Api über JSON Web Tokens sichergestellt. JWT-Tokens sind ein Internet-Standard für die sichere Authentifizierung eines Clients bei einem Server. Der JWT-Token werden bei der Authentifizierung durch die Api generiert und kryptographisch signiert. Anschließend wird der Token an den Benutzer / den Client zurückgegeben.
Der Client überträgt anschließend bei jedem Aufruf den JWT-Token im Header jeder Anfrage mit und weist sich darüber gegenüber der Api – die Api muss also keine Daten zwischenspeichen, stattdessen speichert der Client das Token.
Bei der v.Api erfolgt die Authentifizierung über den normalen v.Soft Benutzernamen und das Passwort. Die v.Api erzeugt dann einen JWT-Token mit den Daten zur Authentifizierung, Informationen zum Benutzer selbst und den Rechten, die der Benutzer bei der v.Api hat.
Funktionsschema der JWT-Token
6. API Versionierung
Für die v.Api stellen wir ein einhetliches Versionierungskonzept zur Verfügung. Mit der Versionsnummer der v.Api kannst du sofort erkennen, welche Version der Api gerade bei dir im Einsatz ist und welche Funktionen aktuell unterstützt werden. Zusätzlich stellen wir über die Versionierung sicher, dass bestimmte Versionen der v.Api untereinander abwärtskompatibel sind.
Die Versionsnummer der Api ist in drei Teile unterteilt. Beispiel: v.Api - Version 1.0.10
- Erste Ziffer: Major-Version
Ändert sich nur bei neuer Code-Basis von v.Soft. - Zweite Ziffer: Minor-Version
Ändert sich wenn die Version nicht mehr abwärtskompatibel ist. - Dritte Ziffer: Release-Version
Ändert sich für neue Features und Funktionen.
Für weitere Details zum Versionierungs-Konzept der v.Api siehe auch v.Api – Versionierung
7. Abbildung von v.Soft Funktionen
Die v.Api ist nach dem Grundsatz aufgebaut, dass die vorhandenen Funktionen und Daten von v.Soft möglichst 1:1 abgebildet werden sollen. Das bedeutet z.b., dass eine Suche in der v.Api genauso funktioniert wie die Suche in v.Soft und bei der selben Eingabe bzw. Suche die selben Daten liefert. Entsprechend müssen bestimmte Funktionen in der v.Api genauso einzeln nacheinander ausgeführt werden wie der Benutzer diese in v.Soft ausführen würde.
Grundsätze der Abbildung
- Die Funktionen der API sind den Masken und den Funktionen von v.Soft möglichst sinngetreu nachempfunden.
- Die Datenstrukturen der API sind (reduzierte) Datenstrukturen aus v.Soft und entsprechen grundsätzlich den Datenstrukturen aus der Datenbank.
- Die Abhängigkeiten zu Fremdschlüsseln und von Zeilen zu Kopfdaten werden beibehalten und müssen einzeln abgefragt werden.
- REST-Designprinzipien werden beibehalten (Ein Aufruf -> Ein Statusübergang)
Motivation für die Abbildung
- Funktionen sind besser nachvollziehbar und verhalten sich immer gleich.
- Funktionalitäten sind zwischen API und Cirrina-Oberfläche austauschbar und können weitergeführt werden.
- Gleiche Datenstrukturen fördern Erweiterbarkeit.
- Weiterentwicklungen und Fehlerbehebung werden erleichtert.
- REST-Designprinzipien fördern Single-Responsibility-Prinzip