Wer sich mit der Planung, dem Design und der Entwicklung von API-Schnittstellen befasst, wird sich früher oder später mit der API-Definition und einer der hierfür populären Beschreibungssprachen auseinandersetzen müssen. Eine gute API zeichnet sich vor allem durch positive Qualitätsmerkmale aus. Hierzu gehören in erster Linie klare Konsistenz, die möglichst einfache Benutzbarkeit und eine geeignete Abstraktion. Die Bedeutung einer hilfreichen Dokumentation sollte von Anfang an sichergestellt sein und darf niemals unterschätzt werden. Sobald die API auch anderen Entwicklern zur Verfügung gestellt werden soll, muss zwingend eine möglichst ausführliche und umfangreiche API-Definition und Beschreibung dokumentiert werden. Eine leistungsfähige Web-API ist nur dann erfolgreich, wenn seine Struktur gut dargestellt wird. Technische Angaben wie angebotene Endpunkte, verwendete HTTP-Methoden und Parameter und wie Requests auszusehen haben, sind dabei essentiell. All diese Angaben sorgen zum einen für eine gute Anwendbarkeit und unterstützen bei entsprechender Formulierung auch die automatische Codegenerierung. Mit welcher Beschreibungssprache eine API-Definition erstellt wird, bleibt dabei dem Entwickler überlassen. Wir beleuchten hier die gängigsten Sprachen wie Open API, Swagger und RAML. Open-API Unter der Federführung der Linux-Fundation wurde 2015 eine spezielle Arbeitsgruppe mit der Bezeichnung „Open-API Initiative“ gegründet. Parallel dazu wurde auch Swagger von SmartBear - dem Toolhersteller der bekannten und geschätzten SoapUI - übernommen. Beide Schritte führten unter dem Aspekt, weiterhin auch herstellerneutral bleiben zu können, zu der Umbenennung von Swagger zur Open-API Specification (OAS). Inzwischen gehören 26 Mitglieder wie Adobe, SAP, PayPal, eBay, Google, MuleSoft und auch Microsoft dazu. Die konsequente Weiterentwicklung findet auf GitHub statt und eröffnet damit jedem Interessierten die Mitarbeit am Projekt durch Issues oder Pull-Requests. Mitte 2017 wurde dann die Version 3.0 von Open-API verabschiedet und veröffentlicht. Gegenüber der Vorversion 2.0 konnte besonders auf der obersten Ebene der Hosts und der Sicherheit ein klarer strukturierter Aufbau erreicht werden. Ein weiterer großer Fortschritt wurde bei der Unterstützung des JSON-Schema erzielt. Basierend auf den Formaten JSON oder YAML 1.2 können unterschiedlichste Sprachen wie Java, JScript, .Net, Ruby, Scala oder auch Gitlab angewendet werden. Auch in Open-API existieren die Ausgangspunkte Contract-/API-First oder alternativ der Programmcode über Code-First. Eine genaue Beschreibung zu Open-API finden Sie in unserem Praxisartikel Open API Spezifikation. Swagger Das Swagger API-Projekt wurde im Jahr 2011 von Tony Tam ins Leben gerufen. In der inzwischen hoch vernetzten Geschäftswelt ist es immer wichtiger verteilte Anwendungen mit zentralen Servern über API-Schnittstellen kommunizieren zu lassen. Lange Zeit wurden APIs vorzugsweise mit der WSDL (Web-Service Description Language) beschrieben. Der wohl größte Nachteil ist die technische Umsetzung von REST-Schnittstellen. Einer der größten Vorteile von Swagger hingegen ist jedoch das sprachenneutrale und maschinenlesbare Format, welches in der Regel mit JSON oder YAML definiert wird. Zusätzlich bietet es einen leistungsfähigen Erweiterungsmechanismus. Swagger verfügt zudem noch über die IDL (Interface Definition Language) für eine vereinfachte Programmierung von RESTful-Schnittstellen. Darüber hinaus unterstützt Swagger sowohl die Code-First- wie auch die Contract-/API-First- Entwicklung. Mit verschiedenen Tools wie die Kernbibliothek (swagger-core), die Visualisierungsoberfläche (swagger-UI), einen leistungsstarken Editor (swagger-Editor) und den Codegenerator (swagger-Codegen) können sehr komfortabel auch leistungsfähige Schnittstellen entwickelt und getestet werden. Im Rahmen der Beschreibung kann auf Swagger-Tooling zurückgegriffen werden. Hier kann auf dem Quellcode basierend automatisiert eine vollständige Dokumentation erzeugt werden. Eine wesentlich detailliertere Darstellung zu Swagger finden Sie in unserem Artikel Swagger. RAML Was mit Swagger als Quasi-Standard für REST-basierte Anwendungen begonnen hat, wurde mit der Open-API Spezifikation klarer strukturiert und erheblich erweitert. Für die Beschreibung einer REST-API jedoch existiert einerseits kein Standard, auf der anderen Seite wurden SOAP-basierte Web Services bislang immer durch WSDL-Dokumente beschrieben. Mit RAML (RESTful API Modeling Language) ist nun ein weiteres wichtiges Werkzeug für das API First Development verfügbar. Dabei ist die Anforderung für eine einheitliche Beschreibung von REST-API’s nicht wirklich neu. Eine API-Definition hält sich in der Regel immer an folgende auszugsweise Inhalte wie Entry-Point’s, Ressourcenpfade, GET-/PUT-Methoden mit Parametern, Geschäftsobjekten, Typen und Fehlercodes. Die Entwickler von Mulesoft fassten die Notwendigkeit und Vorteile der API-Definition in der modernen Beschreibungssprache RAML zusammen. Dabei profitieren sie im hohen Maße von vielen Vorgängern wie WADL und Swagger. Eine API-Beschreibung erfolgt dabei im Dateiformat YAML. Damit ist es durch seine vereinfachte Notierung zum einen sehr gut lesbar, auf der anderen Seite sind auch komplexe Hierarchien sehr gut darstellbar. Eine begleitende Dokumentation kann auch über mehrere Kapitel angegeben werden. Für einzelne Methoden können Query-Parameter definiert und als sogenannte „Traits“ auch in anderen Methoden eingesetzt werden. Details und Anwendungsmöglichkeiten zu RAML finden Sie in unseren TECH-Artikel RAML. Fazit Die hier aufgeführten Beschreibungssprachen haben eine grundsolide Basis und viele Anhänger. Swagger ist aufgrund der hohen Verbreitung und Toolunterstützung der Quasi-Standard für REST-basierte API-Definitionen. Mit RAML steht eine technisch moderne und leichtgewichtige Beschreibungssprache bereit, die verschiedene Werkzeuge zur API-Modellierung bereitstellt. Die Open API Specification basiert auf Swagger und führt klarere Strukturen und sinnvolle Erweiterungen ein und wird sich langfristig wohl als neuer Standard etablieren.

Die inzwischen hohe Vernetzung und Digitalisierung in der Wirtschaft, Industrie, Verwaltung und im privaten Umfeld erfordert auch immer hochwertigere Dienste und Anforderungen an die Softwarestrukturen. Datenbasierte Ökosysteme und Plattformen verwenden inzwischen komplexe und leistungsstarke API-Schnittstellen, um die Geschäftsanforderungen umsetzen zu können. Offenen Schnittstellen für die vielseitige Anwendbarkeit der Daten und Informationen stellen hier eine zentrale Schlüsselposition dar. Je komplexer eine Schnittstelle ausgelegt werden muss, umso wichtiger ist hier eine möglichst offene und definierte Struktur. Diese wird dann mit einer entsprechenden Beschreibungssprache dokumentiert und belegt. Mit Open-API steht den Entwicklern eine moderne und leistungsfähige API-Beschreibungssprache für Ihre Projekte zur Verfügung. Basierend auf den bereits sehr erfolgreich im Markt etablierten Open-Source Tools von Swagger hat sich bereits 2015 unter der Federführung der Linux-Fundation aus der Open-API Initiative das neue Projekt Open-API gegründet. Zu dieser Initiative gehören derzeit 26 aktive Mitglieder, in der nicht wenige Big-Player mit von der Partie sind. Hier finden sich dann renommierte Unternehmen wie Microsoft, Google, SAP, Paypal, Adobe, Smartbear oder MuleSoft wieder. Dies sorgt für eine umfassende Kompatibilität und Struktur bei den bereitgestellten und veröffentlichten Diensten. Seit nun mehr 2017 steht die Version 3 zur Projektierung und Umsetzung von leistungsstarken APIs zur Verfügung. Einer der größten Vorteile von Open-API ist die umfassende Sprachenunterstützung für Java, JScript, .Net, Ruby, Scala oder auch Gitlab. Diese basieren allesamt auf den Formaten von JSON oder auch YAML 1.2 und stellen damit eine sehr hohe Kompatibilität zur Verfügung. Weitere Neuerungen finden sich in der endlich angepassten und erweiterten Unterstützung des JSON-Schemas. Zudem fanden Neuerungen und Neustrukturierungen in den Bereichen Sicherheit und Hosts Einzug. Besonders komfortabel wurde die Wiederverwendung von Komponenten gelöst. In einem eigenen Bereich können nun HTTP-Header, Requests, Responses, Parameter, Callbacks, Links, Objektschemata und Beispiele abgelegt werden. Die Kernelemente von Open API Bereits während der Planung eines API sollen die Anforderungen klar definiert werden. Hier gilt es im besonderen Maße auf die Kernelemente der Funktionalität und späteren Dokumentation einzugehen. Jeder Anwender einer API muss auf die Informationen der verwendeten Parameter, Endpunkte, Rückgabewerte und Sicherheitsfaktoren zugreifen können. Nur so ist eine optimale und effiziente Nutzung der Schnittstelle möglich. Es existieren verschiedene Gruppen von Kernangaben in der Open API, auf die wir im Folgenden detaillierter eingehen werden. Dokumentation Um die einzelnen Bestandteile der API klar abbilden zu können, werden in der Regel auch externe Dokumente zur Erläuterung der API-Funktionen, Parameter, Endpunkte oder Angaben zur Webseite wie Nutzungsbedingungen etc. zur Verfügung gestellt. In dem Bereich Docs können entsprechende Verweise auf diese Dokumente und Schemata eingefügt werden. Das folgende Beispiel zeigt das zu verwendende Format: externalDocs: description: Learn more about user operations provided by this API. url: http://api.api-portal.io/docs/user-operations/ Hinter dem Parameter description: wird eine kurze Beschreibung der Dokumentinhalte eingefügt. Mit dem Parameter url: wird dann auch der Link auf die Dokument-Ressource zur Verfügung gestellt. Details Innerhalb der Sektion Details werden sämtliche Basisinformationen zur API zur Verfügung gestellt. Diese Informationen sind auch API-weit gültig. Dieser Bereich verfügt über wichtige Parameter, die grundsätzlich eingetragen werden sollten. Der folgende Quelltextauszug beschreibt die einzelnen Werte im benötigten Format: info: title: Sample API description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML. version: 0.1.9 servers: - url: http://api.api-portal.io/v1 description: Optional server description, e.g. Main (production) server - url: http://staging.api-portal.io/v2 description: Optional server description, e.g. Internal staging server for testing Der erste Abschnitt info: beschreibt die Funktion der API mit kurzen Worten. Der Parameter title: nennt einen frei wählbaren Titel für die API, der zweite Parameter description: nennt die Kernfunktion dieser API und darf auch externe Links zu einer Referenzquelle beinhalten. Der Abschnitt version: spricht für sich und bildet die aktuell verwendete API-Version ab. Diese Information ist bei unterschiedlichen Revisionen einer API besonders wertvoll. Im Abschnitt servers: wird nun der aktive Host dieser API aufgeführt. Im Parameter url: wird jeder verwendete Basispfad einzeln und detailliert aufgeführt. Mit dem Parameter description: folgt eine jeweils kurze Beschreibung des Pfades. Security Mit dem Abschnitt Security werden alle in der API verwendeten und zugelassenen Authentifizierungsmethoden beschrieben. Zu jedem Eintrag existieren verschiedene Parameter, die auf die Verwendung des Schemas verweisen. Der folgende Quelltextauszug zeigt exemplarisch die korrekte Verwendung: components: securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key OpenID: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access admin: Grants access to admin operations Neben Basic- und Bearer-Auth können auch weitere Schemas angegeben werden. Bei OAuth2 werden mehrere Angaben zu den URLs und den Gültigkeitsbereichen (scopes) vergeben. Hier kann dann gezielt die Zugriffsebene benannt werden. Sobald die Security-Regel im Root eingetragen wird, hat sie für die gesamte API entsprechende Gültigkeit. Hier ein mögliches Szenario, bei dem das Security-Schema OAuth2 nur Schreib- und Lesezugriffe erlaubt: security: - ApiKeyAuth: [] - OAuth2: - read - write Weiterhin unterscheidet man auch die möglichen Authentifizierungsmethoden bezüglich der einzelnen Ressourcen-Operationen wie Lesen und Schreiben. Im folgenden Beispiel wird speziell für den Lesezugriff auf Rechnungsinformationen die Methode OAuth2 mit Adminrechten definiert: paths: /billing_info: get: summary: Gets the account billing info security: - OAuth2: [admin] # Use OAuth with a different scope responses: '200': description: OK Ressources In der Regel verwendet ein API über unterschiedlichste Ressourcen wie Dateien, Formulare oder andere Informationen. Um an diese Daten zu kommen, sind im http-Protokoll auch verschiedene Anfrage- und Zugriffsmethoden definiert. Damit wird beispielsweise einem Browser signalisiert, wie er mit der Anfrage umzugehen hat. Grundsätzlich sind hier 4 Standard-Anfragemethoden vorgesehen, die auf Ressourcen angewendet werden können. Im Folgenden stellen wir diese nebst einer einfachen Beispiel-Parametrisierung vor: GET - Mit dieser HTTP-Methode kann eine Ressource eingelesen werden. Zu beachten ist, dass eine GET-Methode keine Bestandsdaten am Server verändern darf. Um einen bestimmten Eintrag über den Identifier zu finden und auszulesen, setzen Sie die folgende Abfragemethode ein: GET /user/{userID} POST – Die POST-Methode wird in der Regel dazu verwendet, eine neue Ressource zu erstellen, deren URI dem System noch nicht bekannt ist. Dies ist die Standard-Methode zum Anfügen einer neuen Ressource: POST /user 2 PUT – Mit dieser Methode wird das Bearbeiten bzw. Ändern einer bereits bestehenden und bekannten Ressource durchgeführt. Diese Methode wird vor allem für Updates von Daten angewendet: PUT /user 2 DELETE – Um eine bekannte und vorhandene Ressource zu löschen, wird die DELETE-Methode mit dem Identifier verwendet. Beachten Sie hierbei die Ressourcen-Rechte, ob der Methodenaufruf mit den Userrechten überhaupt durchgeführt werden kann: DELETE /user/{userID} Für jede einzelne Ressource werden die entsprechenden Methodenparameter detailliert angegeben. Der folgende Quelltext zeigt exemplarisch die Suche nach einem Benutzerdatensatz an. Als Rückgabewerte werden der Statuscode 200 für die erfolgreiche Abfrage und die Codes 400 bzw. 404 für Fehlermeldungen definiert: paths: /user/{userId}: get: summary: Returns a user by ID. parameters: - name: userId in: path required: true description: The ID of the user to return. schema: type: integer format: int64 minimum: 1 responses: '200': description: A user object. content: application/json: schema: type: object properties: id: type: integer format: int64 example: 4 name: type: string example: Jessica Smith '400': description: The specified user ID is invalid (not a number). '404': description: A user with the specified ID was not found. default: description: Unexpected error Types In den Typendefinitionen der API werden alle verwendeten Geschäftsobjekte detailliert mit ID und den Eigenschaften nebst Wertebereichen beschrieben. Dabei werden auch beschreibende Kategorien verwendet, um die Objekt besser klassifizieren zu können. Im folgenden Beispiel erzeugen Sie ein wiederverwendbares Objekt im Component-Container mit allen relevanten Eigenschaften, Datentypen und Scopes: components: schemas: Category: type: object properties: id: type: integer format: int64 name: type: string Errors Zu jedem API-Request sollten auch ein oder mehrere Statusmeldungen definiert werden. Dies gilt insbesondere für auftretende Fehler. Je genauer Sie jeden API-Aufruf mit Error-Codes ausstatten, umso einfacher wird das Handling der Schnittstelle ausfallen. Unter dem Parameter responses definieren Sie alle Fehlercodes die zurückgegeben werden können. Dokumentieren Sie mit dem Parameter description: auch die Art der Fehlermeldung als Hinweis auf die Quelle. Vor- und Nachteile von Open API Mit der neuen Version 3 der Open API sind viele Fehler bereinigt worden und auch längst fällige Neuerungen dazugekommen. Die große Community und die breite Anwendung durch die Swagger-Tools werden eine schnelle Standardisierung beflügeln. Auch die Teilnahme vieler Big-Player und der nicht vorhandene Vendor-Lock sorgen für mächtig Vorschub. Viele namhafte Frameworks setzen inzwischen auch auf eine breite Open API Unterstützung. Vor allem die breite Neustrukturierung in der Userverwaltung und im Header-Bereich erleichtern den Umgang enorm. Ein weiterer klarer Vorteil sind die nun wiederverwendbaren Objekte über eine eigene Sektion. Doch dort wo Licht, ist meist auch Schatten zu finden. Derzeit sind nur wenige Tools und Entwicklungsumgebungen speziell auf Open API ausgerichtet. Auch die Wiederverwendung von Code-Snippets ist noch nicht vorhanden und es bestehen gewisse Inkompatibilitäten zwischen den Versionen. Diese Unzulänglichkeiten werden aber sicherlich in absehbarer Zeit ausgeräumt. Fazit Die Auszeichnungssprache Open API hat sehr viele Vorteile und damit auch Gemeinsamkeiten mit RAML. Durch die relativ gute Auswahl an Code-Generatoren und den vielen Tools im Ökosystem werden viele Projektleiter jedoch Open API den Vorzug geben. Wer großen Wert auf umfangreiche Sprachenunterstützung legt, ist hier genau richtig. Mittelfristig wird Open API wohl zum neuen Standard in der API-Dokumentation heranwachsen, was die eh schon große Community sicherlich begrüßen wird.

Einführung Einer der größten Vorteile unserer hoch vernetzten digitalen Welt ist die nahezu unerschöpfliche Vielfalt an Informationen, Wissen und praktischen Anwendungen. Für letztgenannte gilt im Besonderen, dass eine moderne Applikation über eine oder mehrere Schnittstellen auf die entsprechenden Ressourcen zugreifen, diese anzeigen und auch bearbeiten kann. Daher gelten für diese APIs auch besondere Vorgaben bei der Projektierung und Entwicklung. Eine derartige Schnittstelle sollte möglichst umfassend und verständlich für alle Beteiligten beschrieben werden. Diese hohe Transparenz hilft auch beim Auffinden von Design- und Programmfehlern. Bereits 2010 hatte der eifrige Programmierer Tony Tam von Wordnik große Probleme, dass für eine strukturierte Beschreibung einer von Ihm zu programmierenden REST-API-Schnittstelle die reine Aufzählung der verwendeten URLs nicht ausreichen würde. Auch die notwendige Kombination von verschiedenen Programmiersprachen und Technologien wie WSDL oder WADL gestaltete sich zu diesem Zeitpunkt besonders schwierig. Die Lösung fand er in der Definition einer eigenen Interface Definition Language (IDL) für REST-API’s und nannte diese Swagger, die nach wie vor als Open Source unter der Apache-Lizenz verfügbar ist. 2015 wurde die Swagger-Definition dann im Rahmen der neu gegründeten Open API Initiative (OAI) konsequenterweise in die Open API Specification (OAS) umbenannt. Die API-Kernelemente in Swagger Die Basis einer API-Beschreibungssprache besteht immer aus der Darstellung der einzelnen Kernelemente wie die Dokumentation, die Zugriffs- und Endpunkte sowie eine detaillierte Beschreibung der verwendeten und möglichen Fehlercodes. Je detaillierter diese Kernelemente beschrieben werden, umso einfacher ist die Anwendung und Wartung der API. Ein weiterer wichtiger Punkt ist die Sicherheit und damit auch die in der Schnittstelle verwendeten Security-Elemente. Ausschlaggebend für den Funktionsumfang sind die in der API vereinbarten Geschäftsobjekte in Form von Typendeklarationen nebst allen verwendeten Parametern und Rückgabewerten. Je genauer diese Angaben in der Schnittstelle beschrieben werden, umso transparenter und einfacher wird deren Anwendung, Wartung und Integration ausfallen. Für die Beschreibung dieser Kernelemente verwenden wir exemplarisch einen fiktiven User-Store, bei dem sich ein Benutzer registrieren und den Shop für sein Haustier nutzen kann. Docs Ein wichtiges Kernelement für die API stellt der Bereich Docs dar. Hierin können alle für die Schnittstelle relevanten Textressourcen und Dokumente als Referenz hinterlegt werden. Dies können zum einen eine Funktionsbeschreibung der API, eine Entwicklerdokumentation oder auch ein Benutzerhandbuch für die Anwender sein. Für die Beschreibung einer Ressource stehen die beiden Parameter description und url zur Verfügung. Das folgende kurze Codeschnippsel zeigt eine mögliche Anwendung: externalDocs: description: "Find out more about Swagger" url: "http://www.api-portal.io" Details Der Bereich Details beinhaltet alle wichtigen Informationen zur gesamten Schnittstelle. Diese Basisinformationen sind damit für die gesamte API gültig. Für die entsprechenden Angaben stehen einige Parameter wie auszugsweise description, version, title oder host zur Verfügung. Die wichtigsten Parameter sind hier basePath und schemes. Mit basePath kann sehr einfach und übersichtlich auf eine Versionierung eingegangen werden, indem man hier das aktuelle Verzeichnis angibt. In schemes werden die für diese API verwendeten Transfer-Protokolle aufgelistet. Im folgenden Quelltextausschnitt sehen Sie eine mögliche Parametrisierung: info: description: "This is a sample server Userstore server." version: "1.0.0" title: "Swagger Users" host: "users.api-portal.io" basePath: "/v2" schemes: - "http" Beachten Sie hier die Möglichkeiten mit den Parametern basePath und version. Trotz einer Version 1.0.0 im Parameter version kann das Basisverzeichnis im Parameter basePath durchaus abweichend gestaltet sein. Security In einer API-Schnittstelle können ohne weiteres auch unterschiedliche Authentifizierungsmethoden verwendet werden. So können problemlos OAuth 2.0, Digest und Pass-Through gemeinsam verwendet werden. Für jeden Authentifizierungstyp gelten dabei ein Satz an notwendigen Parametern wie type, name, scopes oder auch flow. Im folgenden Beispiel verwenden wir OAuth 2.0 für die Authentifizierung und beschreiben dessen Anwendung in verschiedenen Parametern wie folgt: securityDefinitions: userstore_auth: type: "oauth2" authorizationUrl: "http://users.api-portal.io/oauth/auth" flow: "implicit" scopes: write:users: "modify users in your account" read:users: "read your users" api_key: type: "apiKey" name: "api_key" in: "header" Im Parameter type tragen wir OAuth2 als Authentifizierungsmethode ein und setzen den Scope auf die korrespondierenden Write- und Read-Methoden. Über api_key definieren wir den Zugriffsschlüssel nach Name und seinem Vorkommen im header. Ressources Für den Zugriff auf die unterschiedlichen Ressourcen des Hosts über das HTTP-Protokoll werden in der API zunächst die gängigsten Zugriffsmethoden deklariert. Hierzu gehören die 4 Standard-Methodenaufrufe GET, POST, PUT und DELETE. Hierüber wird dem jeweiligen Browser die gewünschte Verarbeitung signalisiert und wie die angefügten Parameter zu verwenden sind. Nachfolgend finden Sie die vier Methodenaufrufe mit einer kurzen Erläuterung beschrieben. GET - Über die GET-Methode wird lesend auf eine definierte Ressource zugegriffen. In unserem fiktiven Beispiel des User-Shops kann hier ein bestimmtes Tier oder Produkt gesucht und danach angezeigt werden. Der Beispielaufruf hierzu lautet vereinfacht dargestellt: GET /user/{userId} POST - Die POST-Methode wird immer dann verwendet, wenn eine neue aber noch nicht vorhandene Ressource erstellt werden soll. Wir können in unserem Beispiel ein neues Haustier mit folgendem Aufruf sehr einfach einfügen: POST /user 2 PUT – Mit dieser Methode kann eine Änderung an einer bereits im System bestehenden Ressource durchgeführt werden. Für unser Beispiel könnte eine Änderung vereinfacht wie folgt durchgeführt werden: PUT /user 2 DELETE - Sofern eine Ressource im Bestand nicht mehr benötigt wird, kann mit sehr einfach über den folgenden Methodenaufruf entfernt werden. Die Identifizierung erfolgt hier über die ID Nummer wie folgt: DELETE /user/{userId} Das Zusammenspiel der Methoden und Parameter wird im folgendem Codefragment kurz dargestellt. Wir gehen davon aus, dass ein registrierter Benutzer im Bestand nach einem zuvor festgelegten Haustier suchen möchte. Hierfür wird die userId verwendet. /user/{userId}: get: tags: - "user" summary: "Find user by ID" description: "Returns a single user" operationId: "getUserById" produces: - "application/xml" - "application/json" parameters: - name: "userId" in: "path" description: "ID of user to return" required: true type: "integer" format: "int64" responses: 200: description: "successful operation" schema: $ref: "#/definitions/User" 400: description: "Invalid ID supplied" 404: description: "User not found" security: - api_key: [] Nach dem Methodenaufruf wird auch der ResponseCode entsprechend ausgewertet und zeigt über die hier implementierten 3 Auswertungscodes, ob die Abfrage erfolgreich war oder die ID-Nummer nicht ausgewertet werden konnte. Das Ergebnis kann dem Benutzer dann formatiert angezeigt werden. Types Im Bereich der types werden nun alle verwendeten Geschäftsobjekte der Schnittstelle eingetragen und verwaltet. Diese Objekte können dann innerhalb der API immer wieder und an verschiedenen Stellen verwendet werden. Die Beschreibung eines Objektes wird über seine Eigenschaften durchgeführt. Um bei unserem fiktiven Beispiel des User-Shops zu bleiben, finden Sie im folgenden Quelltext die Beschreibung des Benutzer-Geschäftsobjektes User mit allen Parameterdefinitionen: definitions: User: type: "object" properties: id: type: "integer" format: "int64" username: type: "string" firstName: type: "string" lastName: type: "string" email: type: "string" password: type: "string" phone: type: "string" userStatus: type: "integer" format: "int32" description: "User Status" xml: name: "User" Eine Objekt-Eigenschaft wie id wird in diesem Quelltext über die Eigenschaften type: und format: beschrieben. Die ID ist somit ein Integer-Wert im Format Int-64. Alle weiteren Eigenschaften werden ähnlich definiert, bis das Objekt vollständig beschrieben ist. Errors Eine der wichtigsten Definitionen einer Schnittstelle sind die möglichen Fehler- oder Response-Codes. Hierüber kann die API eine Auswertung eines Methodenaufrufs vornehmen und bei Fehlern anhand des Fehlercodes beispielsweise eine Klartextmeldung für den Anwender generieren. Die Deklaration erfolgt immer nach dem Schema {Fehlercode: Beschreibung/Meldung}. Im folgenden Beispiel finden Sie die exakte Notation: responses: 200: description: "successful operation" 400: description: "Invalid ID supplied" 404: description: "Order not found" Vor- und Nachteile von Swagger Die API-Entwicklung mit Swagger bietet einige wesentlichen Vorteile. Hier sind zum einen die weit verbreiteten Projekt-Ansätze wie Code-First oder Contract-/API-First zu nennen. Auf der anderen Seite bietet Swagger ein sprachenneutrales und vor allem maschinenlesbares Format an. Die Definitionen können dabei entweder in JSON oder auch YAML codiert werden. Zudem verfügt Swagger auch über einen relativ einfachen Erweiterungsansatz. Die Entwicklung wird dabei von etablierten Tools wie die Kernbibliothek (Swagger-Core), der Swagger-UI für Testing und Visualisierung, dem leistungsstarken Swagger-Editor und dem Codegenerator (Swagger-Codegen) unterstützt. Ein weiterer Pluspunkt ist die enorm große Community und die vielen Code-Snippets für nahezu alle Anwendungsfälle. Gegenüber seinen Konkurrenten kann Swagger allerdings keine Codefragmente flexibel wiederverwenden. Somit sind Includes oder Extensions nicht mehrfach nutzbar, was einen erheblichen Mehraufwand und damit Nachteil in der Programmierung der API darstellt. In einigen Punkten wie beispielsweise der Serverspezifikationen oder der Security kann Swagger nicht mehr mit der neuen OpenAPI Spezifikation 3 mithalten. Content Negotiation und der Ausbau des JSON-Schemas sind weitere Pluspunkte für die modernere API-Beschreibungssprache. Fazit Gerade im Bereich der RESTful-APIs und der beiden weit verbreiteten Projektansätze Code-First und Contract-/API-First ist Swagger eine sehr gute Wahl. Die große Community und die zahlreichen verfügbaren Tools für nahezu alle Programmiersprachen bieten eine extrem breite und professionelle Ausgangsbasis für die Entwicklung von Schnittstellen. Die Wandlung von Swagger zur OpenAPI-Initiative in der aktuellen Version 3.0 bringt allerdings viele Neuerungen und Vorteile. Mehrere Hosts und eine wesentlich klarere Struktur sprechen für die überarbeitete Version. Mit der neuen OpenAPI-Spezifikation in der aktuellen Version 3.0 und der breiten Unterstützung der namhaften Hersteller in der neuen Initiative wird sich in naher Zukunft aber OpenAPI 3.0 durchsetzen und Swagger 2.0 damit schrittweise ablösen. Auch im Bereich der Tools und Codegeneratoren bedarf es für die OAS noch an einiger Aufholarbeit, was letztendlich aber nur eine Frage der Zeit ist.

Der stetig steigende Anteil an Webanwendungen basiert auf der ebenso zunehmenden Vernetzung zwischen Kunden und Unternehmen. Die Interaktion der Teilnehmer wird dabei über API’s geregelt, welche die Apps und die IT-Infrastruktur digital miteinander verbinden. Aus diesem Grund ist es besonders wichtig, dass eine API für seine Anwender möglichst flexibel und transparent gehalten wird. Auch Designfehler in der Projektierungsphase können mit einer gut strukturierten Dokumentation schnell und sicher aufgefunden und behoben werden. Besonders Projekte mit einem API-First-Ansatz unterliegen oft einem Änderungsprozess, der eine lückenlose Darstellung der Schnittstellen und Parameter unabdingbar macht. Mit RAML (RESTful API Modeling Language) existiert eine speziell auf das API-First-Prinzip und die Modellierung von RESTful-API’s ausgelegte Beschreibungssprache. Das Ziel ist hier vor allem die lückenlose Bereitstellung aller Informationen für die Beschreibung und Generierung einer API. Von MuleSoft bereits 2013 als Spezifikation definiert, liegt RAML heute in der aktuellen Versionierung 1 mit dem Release-Datum 2017-07-06 vor. Die Notation der API erfolgt dabei im YAML 1.2 Format. Als Sprachunterstützung werden Java, Node.js, Mule, Phyton und IOT angeboten. Die RAML-Spezifikation wird neben dem Gründer MuleSoft auch von beispielsweise Cisco, VMWare, .Net, PayPal, SOA Software, Kin Lane und AngularJS unterstützt. Die API-Kernelemente in RAML Eine möglichst detaillierte und vollständige Dokumentation zu einer API ist hinsichtlich der Verwendbarkeit und Wartung besonders wichtig. Inhaltlich müssen alle wichtigen Parameter, Geschäftsobjekte, Fehlercodes und Zusatzinformationen genau und idealerweise auch mit kurzen Beispielen beschrieben werden. Die im Folgenden aufgezeigten Kernelemente sollten daher in jeder API-Beschreibung vorhanden sein und möglichst detailliert dargestellt werden. Wir beschreiben die verschiedenen Bereiche mit einem fiktiven Beispiel einer Fluggesellschaft, in der unterschiedliche Aktionen wie Buchungen, Stornos oder Abfragen von Informationen zu leisten sind. Docs Für eine möglichst detaillierte Beschreibung der API-Bestandteile können in der Sektion docs entsprechende Dokumente benannt werden. Auch eine Benutzeranleitung kann hier in Form von Links und Includes integriert werden. Hierzu stehen die zwei Parameter documentation: und title: zur Verfügung, um einen Referenzlink zu beschreiben. Es ist auch eine Mehrfachnennung von Links und Beschreibungen möglich. Der folgende Quelltextauszug zeigt ein Beispiel: documentation: - title: Home content: | Welcome to the airline Fly Away. We are an european low cost airline. You can find the cheapest airline fares within Europe. - title: Languages content: | Please select a language of your choice for our airline API. We offer the following languages: English, German, Spanish, French and Italian. See our library [languages libraries](http://www.google.com). Details Grundlegende Informationen zu der vollständigen API werden in der Sektion Details notiert. Hierfür stehen verschiedene Parameter wie auszugsweise info:, title: oder servers: zur Verfügung. Im nachfolgenden Quelltextauszug sehen Sie ein Beispiel zu unserer fiktiven Airline: title: Airline Fly Away API version: v1 baseUri: http://api.dataliquid.com/airline/{version} description: This API allows to interact with our airline Fly Away API. mediaType: application/json Der Parameter title: sollte die grundlegende Funktionalität der API beschreiben. Die Versionsangabe im Parameter version: ist für die Revisionsverwaltung von Interesse. Mit dem Parameter baseUri: wird der Pfad zur API angegeben, der auch eine Ebene der Versionierung beinhalten kann. In description: vergeben Sie weitere Informationen zur API. Unter mediaType: verzeichnen Sie die für die API verwendete Formatsprache. Security In dieser Sektion werden alle Angaben bezüglich der Sicherheit notiert. Hier stehen in der Regel die Authentifizierungsmethoden, die in der API angewendet werden. Über verschiedene Angaben werden die Sicherheitsebene und weitere Parameter definiert. Der folgende Quelltextabschnitt beschreibt exemplarisch die Authentifizierungseinstellungen für unser fiktives Unternehmen: securedBy: [oauth_2_0] securitySchemes: oauth_2_0: type: OAuth 2.0 displayName: OAuth 2.0 description: | This API supports OAuth 2.0. The necessary ClientId and ClientSecret will be supplied by the provider of the API. Access-Tokens will be issued by means of Id and Secret and are subjected to TimeToLive, short TTL, that is provided when the token is issued. Expired Tokens are rejected by the API with the HTTP Status 403. describedBy: headers: Authorization: type: string displayName: Authorization description: | Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter. example: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3 queryParameters: access_token: type: string displayName: Access Token description: | Used to send a valid OAuth 2 access token. Do not use with the "Authorization" header. example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3 responses: Der erste Parameter securedBy: definiert das anzuwendende Authentifizierungsverfahren, welches als Root über die ganze API gültig ist. Darauf folgen eine oder mehrere Definitionen mit einem Satz an Parametern wie auszugsweise type:, displayName:, describedBy: und queryParameter:. Mit diesen Angaben wird das angewendete Autorisierungsverfahren im Detail beschrieben. Hierauf folgen noch Angaben zum Access-Token access_token: und die möglichen Response-Codes responses:. Ressources Um den Zugriff auf die verschiedenen Ressourcen über die API zu definieren, werden im http-Protokoll unterschiedliche Zugriffsmethoden verwendet. In der Regel kommen hier die vier gängigsten Methodenaufrufe in Frage. Diese signalisieren dem Browser, wie er mit einer Anfrage umzugehen hat und wie die mitgeführten Parameter verwendet werden sollen. In der nachfolgenden Auflistung werden die vier Methodenaufrufe kurz vorgestellt: GET - Über die GET-Methode kann beispielsweise lesend auf eine Ressource zugegriffen werden, ohne die Bestandsdaten zu verändern. Für unsere fiktive Fluggesellschaft würde dieser Aufruf einer Abfrage über einen bestimmten Flug entsprechen. POST - Die POST-Methode ist vorgesehen, um eine neue Ressource zu erstellen. Dabei darf die zu generierende Ressource noch nicht im System vorhanden sein. Dieser Methodenaufruf entspricht in unserem Beispiel der Erzeugung einer neuen Kundenbuchung für einen Flug. PUT - Über diese Methode kann eine Änderung bzw. Ergänzung an eine bereits im System vorhandene Ressource vorgenommen werden. Hier wäre eine Änderung der Flugdaten wie beispielsweise der Abflugzeit in einer bestehenden Buchung ein entsprechendes Beispiel. DELETE - Wenn eine Ressource im System nicht mehr gebraucht wird, kann mit diesem Methodenaufruf eine Löschung durchgeführt werden. Dies wäre der Fall, wenn ein Kunde einen bereits gespeicherten Buchungssatz wieder entfernen möchte. In der API werden zu jedem Methodenaufruf die entsprechenden Parameter detailliert aufgeführt. Am Beispiel unserer Fluggesellschaft sucht ein Besucher auf unserer Webseite unter Verwendung der Suchparameter (queryParameters) gezielt nach passenden Flügen. Im folgenden Quelltext finden Sie die exemplarische Definition der GET-Methode auszugsweise wieder: /flights: get: displayName: Search flights description: Customer searches for flights by using different filters. queryParameters: departure_airport: type: string displayName: Departure airport description: Departure airport according to the IATA airport code. It’s a threeletter code designating many airports around the world. example: "BER" required: false destination_airport: type: string displayName: Destination airport description: Destination airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "LON" required: false flight_type: type: string displayName: Flight type description: Flight is either one way or return. example: "One way" required: false outgoing_flight_date: type: date-only displayName: Outgoing flight date description: The date of the outbound flight. example: "2018-12-11" required: false return_flight_date: type: date-only displayName: Return flight date description: The date of the return flight. example: "2018-12-18" required: false passengers: type: number displayName: Passengers description: Number of flight passengers. example: 1 required: false responses: Types Ein wesentlicher Bestandteil der API-Definition ist die detaillierte Darstellung der verwendeten Geschäftsobjekte mit allen benötigten Parametern. Hier finden wir dann auch die Objekteigenschaften wie departure_airport:, destination_airport: oder price: Einen dieser Objekttypen für die Flugsuche (FlightSearchType) werden wir im folgenden Quelltextauszug kurz vorstellen: types: FlightSearchType: type: object displayName: Flight search type description: User searches for flights and receives information about available flights, date and time, flight number. properties: departure_airport: type: string displayName: Departure airport description: Departure airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "BER" destination_airport: type: string displayName: Destination airport description: Destination airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "LON" price: type: PriceType displayName: Price description: Price of the flight. example: price: 79.99 currency: "EUR" Errors Ein weiterer wichtiger Abschnitt in der API-Definition sind die Statusmeldungen der Kommunikation. Diese sollten möglichst detailliert aufgeführt werden, um eine mögliche Fehlersuche bzw. Benutzermeldung effektiv durchführen zu können. Die Rückgabe einer Fehlermeldung erfolgt dabei im JSON-Format, wie der folgende Quelltextauszug zeigt: responses: 404: body: application/json: type: ErrorType example: | { "reason": "RESOURCE_NOT_FOUND", "message": "Resource not found", "trace_id": "550e8400-e29b-11d4-a716-446655440000" } Vor- und Nachteile von RAML Gegenüber anderen Auszeichnungssprachen wie Open API bietet RAML eine einfache und komfortable Möglichkeit, wiederkehrenden Quellcode und Schemas einbinden zu können. Zudem existiert eine durchaus aktive Community, die einen hervorragenden Support leistet und Code-Snippets zur Verfügung stellt. Mit professionellen Tools wie die Atom Plugin API Workbench oder das Mule Studio ist eine schnelle und komfortable Projektierung möglich. Nachteilig sind hier die wenigen verfügbaren Tutorials, die einem Neuling den Einstieg erleichtern könnten. Problematisch ist auch die fehlende Abwärtskompatibilität der unterschiedlichen Versionen sowie die relativ geringe Sprachenvielfalt gegenüber andern Beschreibungssprachen. Fazit Wer vom Grundsatz her schnelle und saubere Designs für RESTful-API’s benötigt, ist mit der Beschreibungssprache RAML derzeit klar im Vorteil. Besonders mit Blick auf agile API-First-Projekte sollte die Dokumentation möglichst einfach aber transparent gehalten werden. Aufgrund der flexiblen Wiederverwendbarkeit von Objekten und Codefragmenten kann RAML gegenüber der Konkurrenz deutlich punkten. Die Integration von XML-Schemata ist mit RAML in Sekunden erledigt. Vor allem die Bedienung der API Workbench ist sehr einfach und intuitiv gelöst. Dennoch bleibt anzumerken, dass aufgrund neuerer Entwicklungen und fortschreitender Standards die Auszeichnungssprache Open API deutlich an Zulauf gewinnt und in absehbarer Zeit wohl als neuer Standard definiert wird.

Die hohe Vernetzung von Mobile-Apps, Cloud-Anwendungen und eingesetzter Software as a Service (SaaS) in der Wirtschaft, Industrie sowie im privaten Umfeld stellen hochwertige Anforderungen an Dienste und Softwaresysteme. Bei der Realisierung von Geschäftsanforderungen werden inzwischen komplexe und leistungsstarke API-Schnittstellen aus der API Economy genutzt. Der zentrale Schlüssel der angebotenen Dienste sind die vielseitigen Funktionen und Informationen die durch die offenen Schnittstellen genutzt werden können. Viele der täglich genutzten Anwendungen basieren auf verschiedenen miteinander verbundenen Diensten. Fällt eine der beteiligten Schnittstellen aus, funktioniert der angebotene Dienst nicht mehr! Um sicher zu stellen, dass die Funktionalität, Zuverlässigkeit, Leistung und Sicherheit der APIs erfüllt werden, sind API-Tests ein Muss. Bei API-Tests werden die APIs (Application Programming Interfaces) direkt und im Rahmen von Integrationstests getestet. Die Tests werden auf Nachrichtenebene durchgeführt. Dabei werden die eingehenden Daten sowie die erwarteten Ergebnisse der Schnittstellen geprüft. Durch die regelmäßige und automatisierte Ausführung der Tests während des API Lifecycle ist sichergestellt, dass die APIs fehlerfrei und stabil ihren Dienst verrichten. Die Qualitätssicherung ist ein wichtiger Bestandteil in der Bereitstellung von hochverfügbaren APIs.

Leistungsstarke APIs zeichnen sich durch einen hohen Funktionsumfang aus. Für die Akzeptanz bei den API Konsumenten stehen neben den Funktionen, die fachlichen Daten im Vordergrund. Business Objects oder Geschäftsobjekte definieren die fachlichen Datenstrukturen, welche von der jeweiligen API Funktion mit dem Konsumenten ausgetauscht werden können. API Ressourcen (Funktion einer API) unterscheiden zwischen Geschäftsobjekten für die Anfrage (Request) als auch für die Rückgabe (Response). Alle verwendeten Geschäftsobjekte einer API werden in der API Definition beschrieben und verwaltet. Die Business Objects können innerhalb einer API wiederverwendet werden. Als Beispiel nehmen wir eine Order API, mit der neue Aufträge erstellt und der Auftragsstatus abgerufen werden kann. Wird über die API eine Order angelegt, so muss die Datenstruktur des OrderTypes an die API übermittelt werden. In der Datenstruktur sind die Datenfelder und Datentypen definiert. Der Datentyp gibt an von welcher Art das Datenfeld ist, z. B. Zahlen, Zeichenketten oder Listen. Ein OrderTyp besteht aus folgenden Informationen: Order Number Customer Number Order Date Order Items Order Status Die gängigen API Spezifikationen unterstützen nahezu alle Datentypen. Die folgenden einfachen Datentypen werden am meisten verwendet: string (Zeichenkette) number (Dezimalzahl) integer (Ganzzahlen) boolean (Wahrheitswerte true, false) array (Liste von Werten) date (Datum) Bei den oben genannten Datenfelder aus unserem Beispiel werden nun die Datentypen festgelegt. Eine Auftragsnummer kann aus Zeichen und Zahlen bestehen, daher legen wir string fest. Die Kundennummer besteht nur aus Zahlen und ist damit number. Das Auftragsdatum wird gemäß dem internationalen Datums- und Zeitformat ISO 8601 als date-only deklariert. Die Auftragspositionen ist ein array, da mehrere Positionen in einem Auftrag enthalten sein können, die als eigenständiges Geschäftsobjekt definiert werden. Zusätzlich können weitere Facetten eines Datenfeldes deklariert werden. Je umfassender eine API definiert wird, je stabiler und belastbarer ist eine API. Durch Facetten können bei einem Datenfeld des Typs string die minimale und maximale Länge festgelegt werden. Das Feld darf beispielsweise mindestens 2 Zeichen und maximal 20 Zeichen enthalten. Wird das Datenfeld Preis vom Typ number beschrieben, kann der Minimalwert und Maximalwert sowie die Nachkommastellen definiert werden. Der Preis muss als Beispiel mindestens 0.00 und maximal 5.000 einer Währungseinheit betragen. Zwei Nachkommastellen sind zugelassen. Bei dem Datenfeld Auftragsstatus können die Beispielwerte NEW, SHIPPED, DELIVERED und CANCELED angegeben werden, damit kann der User das Datenfeld und dessen Nutzung viel einfacher verstehen. Für jedes Datenfeld kann ein fachlicher Beispielwert angegeben werden, dies schafft einen erheblichen Mehrwert für den User, da das Verständnis und Einsatzbarkeit der API praktisch verdeutlicht wird. Durch eine starke Ausprägung der Geschäftsobjekte erreicht die API eine hohe Transparenz der fachlichen Objekte. Damit erleichtern sie es Interessenten und Entwicklern die Schnittstellen sowie die dahinterstehenden fachlichen Prozesse leicht zu verstehen und einzusetzen.