Einleitung APIs spielen in der Geschäftswelt eine immer wichtigere Rolle. Diese Schnittstellen ermöglichen eine nahtlose Kommunikation zwischen verschiedenen Softwarelösungen und tragen maßgeblich zur digitalen Entwicklung bei. Unternehmen stehen unter Druck, ihre Prozesse zu optimieren und innovative Lösungen anzubieten, um im Wettbewerb erfolgreich zu sein. Durch die steigende Vernetzung von Systemen und Geräten wird die Integration von Daten und Services immer relevanter. Eine durchdachte API-Strategie kann nicht nur als Wachstumsfaktor fungieren, sondern auch entscheidend dazu beitragen, sich von Mitbewerbern abzugrenzen. In diesem Artikel wird untersucht, wie APIs als Schlüsselfaktor für Innovationen wirken und welche Rolle sie im Kontext der modernen Unternehmenslandschaft einnehmen. Bedeutung von APIs für die digitale Transformation Die digitale Entwicklung erfordert innovative Ansätze, um mit den sich schnell verändernden Marktbedingungen Schritt zu halten. Application Programming Interfaces, kurz APIs, spielen hierbei eine tragende Rolle. Diese Schnittstellen ermöglichen es Unternehmen, digitale Services schneller und effizienter bereitzustellen. APIs fungieren als Innovationstreiber, indem sie die Entwicklung neuer Geschäftsmodelle beschleunigen und die Flexibilität erhöhen. Sie bieten die Möglichkeit, bestehende Softwarelösungen nahtlos zu integrieren und neue Funktionalitäten hinzuzufügen, ohne umfangreiche Änderungen an der Grundarchitektur vorzunehmen. Ein wesentlicher Vorteil der Nutzung von APIs liegt in der höheren Skalierbarkeit. Durch die einfache Anbindung externer Services können Unternehmen ihre Reichweite erheblich steigern. Dies verbessert nicht nur das Kundenerlebnis, sondern ermöglicht auch eine schnellere Anpassung an Marktbedürfnisse. Unternehmen, die APIs effektiv nutzen, profitieren von verschiedenen Aspekten, wie der schnelleren Markteinführung neuer Produkte, einer verbesserten Zusammenarbeit mit Partnern und der Möglichkeit, Daten in Echtzeit auszutauschen. Diese Faktoren tragen zur Stärkung der Wettbewerbsfähigkeit bei und fördern das Wachstum in der API-Economy. Insgesamt ist die Implementierung von APIs ein wesentlicher Schritt für Unternehmen, die sich in der digitalen Landschaft behaupten möchten. Die Vorteile von Flexibilität und Skalierbarkeit machen APIs zu einem unverzichtbaren Werkzeug für die erfolgreiche digitale Entwicklung. Durch die optimale Nutzung dieser Technologien können Unternehmen nicht nur ihre Effizienz steigern, sondern auch ein herausragendes Kundenerlebnis schaffen, das den heutigen Erwartungen gerecht wird. API-getriebene Geschäftsmodelle API-getriebene Geschäftsmodelle bieten Unternehmen die Möglichkeit, neue Umsatzquellen zu erschließen und ihre Reichweite durch Partnerökosysteme zu erweitern. APIs, oder Anwendungsprogrammierschnittstellen, ermöglichen es verschiedenen Softwareanwendungen, miteinander zu kommunizieren und Informationen auszutauschen. Dies eröffnet zahlreiche Chancen für innovative Monetarisierungsstrategien und die Integration in bestehende Plattformen. Die direkte Monetarisierung von APIs kann auf unterschiedliche Weisen erfolgen. Unternehmen haben die Möglichkeit, Lizenzmodelle zu entwickeln, bei denen Partner für den Zugang zur API zahlen. Alternativ können Pay-per-use-Modelle implementiert werden, sodass die Kosten abhängig von der tatsächlichen Nutzung entstehen. Freemium-Strategien bieten einen Einstieg mit kostenlosen Basisdiensten und ermöglichen es, durch Premium-Funktionen zusätzliche Einnahmen zu generieren. Ein Ökosystem-Ansatz ist entscheidend, um den Wert von APIs zu maximieren. Durch die Integration in Plattformen und die Zusammenarbeit mit Partnern wird die Wertschöpfung gefördert. Unternehmen wie Stripe, Twilio und Salesforce demonstrieren erfolgreich, wie APIs nicht nur als Produkte, sondern auch als strategische Differenzierungsmerkmale fungieren können. Diese Beispiele zeigen klar, wie wichtig die API-Monetarisierung und Partnerintegration in der heutigen Geschäftswelt sind. Unternehmen, die diese Strategien umsetzen, können nicht nur ihre Reichweite erhöhen, sondern auch langfristige Beziehungen zu Partnern aufbauen und ihre Marktposition nachhaltig stärken. Strategische Aspekte einer API-First-Organisation Der Einsatz von APIs wird immer wichtiger. Eine API-First-Organisation stellt sicher, dass APIs von Anfang an in den Entwicklungsprozess integriert werden. Im Gegensatz dazu steht das Konzept des API-Bolt-On, bei dem APIs nachträglich hinzugefügt werden. Während API-First eine einheitliche Strategie und damit verbundene Vorteile wie verbesserte Zusammenarbeit und schnellere Markteinführung bietet, kann API-Bolt-On zu Inkonsistenzen und längeren Entwicklungszeiten führen. Um einen Kulturwandel in Richtung API-First zu vollziehen, sind Schulungen und eine klare Kommunikation entscheidend. Ein weiterer wesentlicher Aspekt ist die Governance und die Einhaltung von Standards. Klare Richtlinien für die Entwicklung und Dokumentation von APIs tragen dazu bei, dass alle Beteiligten auf dem gleichen Stand sind. Ein effektives API-Governance-Modell kann folgende Aspekte umfassen: die Festlegung von Designprinzipien, die Einführung von Überprüfungsprozessen und die Sicherstellung einer umfassenden Dokumentation. Diese Maßnahmen fördern nicht nur die Konsistenz, sondern auch die Qualität der entwickelten APIs. Zusammenfassend lässt sich sagen, dass der erfolgreiche Einsatz von APIs sowohl kulturelle als auch technische Voraussetzungen erfordert. Die Implementierung einer API-First-Strategie und die Etablierung klarer Governance-Strukturen sind notwendig, um die Vorteile von APIs voll auszuschöpfen und einen nachhaltigen Wettbewerbsvorteil zu erzielen. Technologische Grundlagen und API-Ökosysteme Die API-Landschaft ist vielfältig und dynamisch, was eine umfassende Auseinandersetzung mit den unterschiedlichen Technologien und Schnittstellen erfordert. Bei der Auswahl des passenden API-Designs spielen verschiedene Ansätze eine wichtige Rolle. REST ist bekannt für seine Einfachheit und breite Unterstützung, während GraphQL eine flexible Abfrage ermöglicht und gRPC hohe Effizienz in der Kommunikation zwischen Microservices gewährleistet. Jede dieser Technologien hat ihre spezifischen Vor- und Nachteile, die bei der Entscheidung für eine Implementierung berücksichtigt werden sollten. Ein weiterer relevanter Aspekt in der Architektur moderner Anwendungen sind Microservices, die eine modulare Struktur fördern. In Verbindung mit API-Gateways bieten sie eine zentrale Anlaufstelle für die Verwaltung von Schnittstellen, die es Entwicklern ermöglicht, ihre Dienste effizient zu orchestrieren. Diese Struktur hilft nicht nur bei der Skalierbarkeit, sondern auch bei der Wartung der einzelnen Komponenten. Die Erfahrung von Entwicklern spielt eine wesentliche Rolle im Erfolg von APIs. Benutzerfreundliche Dokumentation, umfassende Tutorials und interaktive Sandboxes sind wichtig, um die Integration und Nutzung von APIs zu erleichtern. Eine positive Entwicklererfahrung fördert die Akzeptanz und Nutzung der API, was letztendlich zu einer besseren Produktivität führt. Zusammenfassend lassen sich einige Kerntechnologien und Konzepte im API-Ökosystem identifizieren. Dazu gehören REST, GraphQL und gRPC, die verschiedene API-Design-Ansätze repräsentieren. Zudem sind Microservices und API-Gateways entscheidend für eine strukturierte Service-Architektur. Schließlich spielt die Erfahrung von Entwicklern eine zentrale Rolle, um die Nutzung der APIs zu optimieren. Herausforderungen und Best Practices Die Implementierung von APIs kann eine Vielzahl von Herausforderungen mit sich bringen, die oft als Hindernisse wahrgenommen werden. Neben den technischen Aspekten sind auch rechtliche Vorgaben und Nutzererwartungen von großer Relevanz. Um die Integration erfolgreich zu gestalten, sollten einige bewährte Praktiken beachtet werden, die in den folgenden Bereichen liegen. Ein zentrales Thema ist die Sicherheit und Compliance. Hierzu gehören Authentifizierungsmechanismen, die sicherstellen, dass nur berechtigte Personen Zugriff haben. Darüber hinaus ist die Verschlüsselung von Daten wichtig, um diese vor unbefugtem Zugriff zu schützen. Schließlich müssen auch rechtliche Vorgaben beachtet werden, die je nach Branche variieren können. Ein weiterer kritischer Punkt ist die Performance und Skalierung der API. Durch effektives Caching lassen sich Ladezeiten erheblich reduzieren, was die Interaktion mit der API verbessert. Zudem ist die Versionierung von APIs wichtig, um sicherzustellen, dass bestehende Anwendungen weiterhin kompatibel bleiben. Monitoring-Tools helfen dabei, die Leistung der APIs kontinuierlich zu überwachen und Engpässe rechtzeitig zu identifizieren. Das Lifecycle Management spielt ebenso eine wesentliche Rolle. Hierbei sollten Strategien zur Versionierung sowie zur Wartung und Deprecation von APIs berücksichtigt werden. Eine durchdachte Planung in diesen Bereichen schützt vor potenziellen Problemen und sorgt für eine reibungslose Integration. Die Berücksichtigung dieser Aspekte kann die Implementierung von APIs erheblich erleichtern und dazu beitragen, dass Anwender eine positive Erfahrung haben. Zukunft und Trends Die Entwicklung im Bereich der APIs schreitet dynamisch voran und beeinflusst maßgeblich, wie Unternehmen ihre digitale Infrastruktur gestalten. Eine der zentralen Tendenzen ist die Hinwendung zu event-driven und asynchronen APIs, da die Nachfrage nach Echtzeit-Kommunikation kontinuierlich wächst. Diese Art der Architektur ermöglicht es Anwendungen, schneller auf Ereignisse zu reagieren, was in einer zunehmend vernetzten Umgebung unverzichtbar ist. Ein weiterer bemerkenswerter Trend ist der Übergang zu serverless und Edge Computing. Diese Technologien verändern die Art und Weise, wie Dienstleistungen bereitgestellt werden, indem sie die Notwendigkeit verringern, eigene Server zu verwalten. Stattdessen können Entwickler Ressourcen bedarfsgerecht nutzen und so die Effizienz steigern. Zudem gewinnen APIs, die auf Künstlicher Intelligenz basieren, immer mehr an Einfluss. Machine Learning und KI-Services sind nicht mehr nur Zusatzangebote, sondern integrale Bestandteile einer modernen API-Strategie. Unternehmen können durch den Einsatz von KI-APIs ihre Prozesse optimieren und personalisierte Erlebnisse schaffen. Zusammenfassend lassen sich die kommenden Entwicklungen im API-Bereich in folgenden Bereichen zusammenfassen: Event-driven und asynchrone APIs zur Unterstützung von Echtzeit-Kommunikation, serverless und Edge Computing zur Optimierung der Infrastruktur sowie die Integration von KI-APIs zur Verbesserung von Dienstleistungen. Diese Trends zeigen, dass APIs nicht nur technische Werkzeuge sind, sondern auch Schlüsselkomponenten für Innovationsstrategien in Unternehmen. Fazit Die Implementierung einer erfolgreichen API-Strategie ist maßgeblich für die zukünftige Stabilität eines Unternehmens. Der vorliegende Leitfaden bietet eine klare Struktur und praxisnahe Ansätze, um diesen Prozess effizient zu gestalten. Eine sorgfältige Planung und regelmäßige Überprüfung der gewählten Maßnahmen sind notwendig, um sicherzustellen, dass die API-Strategie den sich wandelnden Anforderungen des Marktes gerecht wird. Ein wichtiger Aspekt ist die kontinuierliche Anpassung und Skalierung der entwickelten Lösungen. Durch das Sammeln von Nutzerfeedback und das Analysieren von Leistungsdaten können Optimierungspotenziale identifiziert und genutzt werden. So bleibt die API-Strategie nicht nur relevant, sondern trägt auch aktiv zur Innovationskraft des Unternehmens bei. Letztlich zeigt sich, dass eine durchdachte API-Strategie technische Vorteile mit sich bringt und gleichzeitig einen nachhaltigen Wettbewerbsvorteil schafft.

APIs – die Revolution für das vernetzte Auto Neben dem eigenen Heim und der Arbeitsstätte hat sich das Auto schon seit längerem zum dritten Lebensraum entwickelt. Es gibt wenige Szenarien, in denen der moderne Mensch mehr Zeit zubringt. Dem entsprechend verlagern sich auch viele Aufgabenbereiche des alltäglichen Lebens nach und nach in das Auto. Erst die konsequente Vernetzung des Wagens mit seiner Umwelt, wie sie durch den Einsatz von APIs möglich wird, macht diese Erweiterung des Nutzungsprofils im fahrbaren Untersatz möglich. Der Wagen als reines Transportmittel ist Vergangenheit Das Telefonieren im Auto als einziges Mittel der vernetzten Kommunikation genügt den meisten Nutzern nicht mehr. Viel zu wichtig für die moderne Lebensgestaltung sind die Möglichkeiten, berufliche Verrichtungen und private Angelegenheiten während der Fahrt abzuwickeln. Das Thema ist Autofahrern so wichtig, dass laut einer Studie der McKinsey Unternehmensberatung aus dem Jahr 2015 37 Prozent der Teilnehmer sogar einen Markenwechsel in Kauf nehmen würden, um ein gut vernetztes Auto nutzen zu können. Besonders markant ist der Steigerungsrate: Im Vorjahr bekundeten das nur 20 Prozent der Befragten. Automobilhersteller als API-Pioniere Laut einer Untersuchung von Microsoft nehmen die Konstruktionsabteilungen der Automobilhersteller heute eine Spitzenstellung unter den Entwicklern von API-Implementationen in Kraftfahrzeugen ein. Dabei liegt das Anwendungsspektrum in allen Bereichen der automobilen Technologie. Insbesondere Apps auf mobilen Endgeräten werden die Zukunft der API-Entwicklung bestimmen. Das beginnt bereit beim Kauf, um das maßgeschneiderte Auto auf dem Smartphone oder Tablet in jedem Detail zu konfigurieren. Automobilhersteller gehen davon aus, dass diese durch APIs ermöglichte komfortable Benutzerumgebung insbesondere die Markentreue und die Kundenbindung fördern werden. Das Internet der Dinge hat gerade in der Automobilindustrie beim konsequenten Einsatz von APIs besondere Bedeutung. Hier punktet vor allem die Verknüpfung von Hersteller, Händler und Zulieferer. Das führt zu den unterschiedlichsten Anwendungsszenarien. Navigation immer auf dem neuesten Stand Ein Assistenzsystem, das über eine API gesteuert wird, kann das digitale Kartenmaterial des Navigationssystems in Echtzeit auf dem neuesten Stand halten, komplett mit veränderten Straßenverläufen, aktuellen Behinderungen durch Baustellen oder Staulagen durch Verkehrsunfälle. Das erlaubt eine dynamische Routenplanung, die sich an Echtzeitdaten orientiert. Technische Probleme proaktiv erkennen Eine Reihe von Sensoren, die in relevante Bauteile und Funktionsgruppen integriert sind, übermitteln per API ihre Erkenntnisse an den Hersteller. Erkannte Problemlagen bringen zweifachen Nutzen: Zum einen erhält der Fahrer die Chance, den noch nicht eingetretenen Schaden bereits im Vorfeld zu verhindern. Zum anderen unterstützen die eintreffenden Informationen den Hersteller dabei, bei Häufung gleichartiger Problemmeldungen konstruktive Verbesserungen am Fahrzeug vorzunehmen. Das Auto fernbedienen – über APIs kein Problem Auf zahlreiche Funktionen und Informationen hat der Fahrer oder die Fahrerin per App Zugriff, unabhängig davon, ob sich der aktuelle Aufenthaltsort im Auto befindet oder nicht: Vergessen, die Tür zu verriegeln? Per App lässt sich der aktuelle Status bequem von der Couch aus ermitteln und die Verriegelung nachholen. Muss morgen getankt werden? Ein Blick auf die per API gesteuerte Tankanzeige erlaubt das Ablesen des aktuellen Benzinstands – und des Ölstands gleich mit. Wie weit reicht die Restladung im Akku des Elektroautos? Über die App ist die Information sofort zu Hand, komplett mit einer Schätzung über die möglichen Restkilometer. Das sind nur einige Beispiele der vernetzten Datenkommunikation. Weitere Anwendungen sind beispielsweise das vernetzte Fahrtenbuch und die Information darüber, wann die nächste Inspektion fällig ist. Services in allen Bereichen Das Anwendungsspektrum für Funktionen, die per API möglich werden, wächst ständig. Bereits heute erlauben Kfz-Apps, den nächsten Parkplatz oder das in fremder Umgebung abgestellte Fahrzeug ausfindig zu machen. Auch die Suche nach der nächsten Tankstelle ist heute in vielen Fahrzeugen ebenso Standard wie die Navigation zu speziellen Zielpunkten, vom Feinschmeckerrestaurant über den Geldautomaten bis zum Krankenhaus. Doch das ist nur der Anfang. Erste Anwendungen zu Restaurantreservierungen oder Hotel– und Flugbuchungen zeigen, wohin die Reise geht. APIs als zugrunde liegende Technologie werden in Zukunft Lösungen ermöglichen, an die heute noch niemand denkt. Fazit Das Auto ist längst nicht mehr nur Transportmittel. Als maßgebliches Lebensumfeld wird es eine ständig steigende Zahl an beruflichen und privaten Aktivitäten unterstützen. Besondere Bedeutung gewinnen dabei die Faktoren Sicherheit, ortsunabhängiger Informationsaustausch und Echtzeit-Kommunikation. So wird das Auto zu einer zentralen Leitstelle für die private und berufliche Lebensgestaltung.

Mit einem API Developer Portal können Sie Ihre Schnittstellen sowie interaktive Dokumentation schnell und einfach einer breiten Masse als Self-Service bereitstellen. Anbieter von Schnittstellen sind in der Regel Organisationen oder Firmen die Ihre Produkte oder Daten durch Schnittstellen mit anderen Parteien teilen. Dabei kann es sich um Neukunden, bestehende Geschäftspartner, Software-Entwickler oder Projekte handeln, die von einer Prozessautomatisierung profitieren. Ein API Portal führt die Schnittstellen auf einer zentralen Plattform sichtbar zusammen. Anstelle Schnittstellen dezentral in Entwicklerteams oder Abteilungen vorzuhalten, werden die APIs in dem API Katalog zusammengeführt und können dort effektiv verwaltet und veröffentlicht werden. Der API Explorer stellt sehr effektiv die angebotenen Funktionen und Daten einer Schnittstelle dar. Die integrierten Business Prozesse ermöglichen eine reibungslose Zusammenarbeit mit Ihren Kunden und dessen Entwicklern. Das Portal erlaubt es Entwickler Informationen über die Schnittstellen zu beziehen, die Funktionalitäten abzurufen und Schnittstellen durch die Try Out Funktion direkt zu testen. Zugriff auf eine API kann der Entwickler selbt mit Hilfe der Self-Service Funktion anfordern. Die Code Generierung ist ein wichtiger Beschleunigungsfaktor! Dabei generiert das Portal einen vollwertigen API Client auf Knopfdruck! Die kostspielige Entwicklung eines API Clients entfällt damit vollständig. Mit der gewonnenen Zeit bringen Sie Ihre Leistungen deutlich schneller an den Markt. Zu den Funktionen eines API Developer Portal gehören unter anderem: Zentrale Verwaltung im API Katalog Anwendungen registrieren Zugriff für eine API anfordern Zugangsdaten zurücksetzen Interaktive API Dokumentation bereitstellen Try-Out Funktion Code Generierung von API Clients Zentrale Benutzerverwaltung Business Workflows Das API Portal beschleunigt Sie bei der Umsetzung Ihre API Strategie. Neben der Zeitersparnis erreichen Ihre APIs eine deutliche höhere Marktreichweit und werden für potentielle Konsumenten sichtbar.

Installation und Einrichtung von Swagger Swagger ist ein leistungsstarkes Open-Source-Tool zur API-Dokumentation. Es dient der strukturierten Beschreibung, Visualisierung und Interaktion mit APIs. Entwickler profitieren von einer klaren, interaktiven Dokumentation, die die Nutzung und Wartung von APIs erheblich erleichtert. Mit Swagger können API-Spezifikationen übersichtlich erfasst und dargestellt werden, wodurch der aktuelle Stand einer API präzise abgebildet wird. Dies fördert nicht nur die Nachvollziehbarkeit, sondern erleichtert auch die Zusammenarbeit zwischen Entwicklern. Vor der Nutzung von Swagger muss es je nach Technologie-Stack installiert und eingerichtet werden, wobei verschiedene Integrationsmöglichkeiten zur Verfügung stehen. Installation Je nach Technologie-Stack gibt es verschiedene Möglichkeiten, Swagger zu integrieren. Die gängigsten Optionen sind: Swagger UI, eine Benutzeroberfläche zur Visualisierung und Interaktion mit API-Dokumentationen. Diese kann über ein CDN oder lokal eingebunden werden und bietet eine interaktive Ansicht der API. Swagger Editor, ein Online-Editor, mit dem API-Spezifikationen direkt geschrieben und getestet werden können. Dies erleichtert die Erstellung und Anpassung der Dokumentation erheblich. Swagger Codegen, ein Tool zur Generierung von API-Client-Bibliotheken und Server-Stubs aus einer Swagger-Spezifikation. Damit lassen sich verschiedene Programmiersprachen unterstützen und eine automatische Codegenerierung ermöglichen. Swagger für verschiedene Frameworks, wie z. B.: Node.js (Express.js): Installation mit npm install swagger-ui-express Spring Boot (Java): Integration mit springfox-swagger2 Python (Flask): Nutzung von flasgger Einrichtung Nach der Installation muss Swagger in das Projekt eingebunden werden. Die Einbindung hängt von der verwendeten Umgebung ab. In einer Express.js-Anwendung sieht die Integration beispielsweise folgendermaßen aus: const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./swagger.json'); const app = require('express')(); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); app.listen(3000, () => console.log('Server läuft auf Port 3000')); Sobald die Anwendung gestartet wurde, kann die API-Dokumentation im Browser unter http://localhost:3000/api-docs aufgerufen werden. Dort sind alle Endpunkte übersichtlich dargestellt und können interaktiv getestet werden. Swagger API Endpunkte erstellen: Erste Schritte Um eine API mit Swagger zu dokumentieren, muss eine Swagger 2.0-Spezifikation erstellt werden. Diese kann in YAML oder JSON geschrieben werden und beschreibt die API-Endpunkte detailliert. Dabei werden nicht nur die verfügbaren Routen definiert, sondern auch die erwarteten Parameter und Antwortstrukturen festgelegt. Ein einfaches Beispiel für einen API-Endpunkt könnte folgendermaßen aussehen: swagger: '2.0' info: title: Beispiel API description: Eine einfache API zur Demonstration von Swagger version: 1.0.0 host: localhost:3000 schemes: - http paths: /users: get: summary: Liste aller Benutzer abrufen produces: - application/json responses: '200': description: Erfolgreiche Antwort schema: type: array items: type: object properties: id: type: integer name: type: string Components: Wiederverwendbare Definitionen Swagger ermöglicht die Wiederverwendung von Komponenten wie Schemas, Parametern und Antworten, um eine konsistente und wartbare API-Dokumentation zu gewährleisten. Die components-Sektion in OpenAPI 3.0 entspricht in Swagger 2.0 der definitions-Sektion. Ein Beispiel für eine Wiederverwendung von Definitionen: swagger: '2.0' info: title: API mit wiederverwendbaren Komponenten version: 1.0.0 host: localhost:3000 schemes: - http definitions: User: type: object properties: id: type: integer name: type: string paths: /users: get: summary: Liste aller Benutzer abrufen produces: - application/json responses: '200': description: Erfolgreiche Antwort schema: type: array items: $ref: '/definitions/User' Hier wird das User-Schema in der definitions-Sektion definiert und anschließend bei der Antwort des /users-Endpoints wiederverwendet. Änderungen an diesem Schema wirken sich auf alle Endpunkte aus, die diese Definition referenzieren, wodurch Konsistenz gewahrt bleibt. Allerdings sollten Änderungen mit Bedacht durchgeführt werden, um unerwartete Auswirkungen auf bestehende API-Clients zu vermeiden. Dies sorgt für eine bessere Wartbarkeit, da Änderungen nur an einer Stelle vorgenommen werden müssen. Security: API-Authentifizierung und Autorisierung Eine gut gesicherte API ist essenziell, um unberechtigten Zugriff zu verhindern. Dabei ist es wichtig, zwischen Authentifizierung und Autorisierung zu unterscheiden. Die Authentifizierung stellt sicher, dass ein Nutzer oder System tatsächlich derjenige ist, der er vorgibt zu sein (z. B. durch API-Keys oder OAuth2). Die Autorisierung hingegen bestimmt, welche Aktionen ein authentifizierter Nutzer durchführen darf (z. B. Lese- oder Schreibrechte). Swagger 2.0 unterstützt verschiedene Authentifizierungsmethoden, darunter API-Keys, OAuth2 und Basic Authentication. Ein Beispiel für eine API, die mit einem API-Key geschützt ist: swagger: '2.0' info: title: Geschützte API version: 1.0.0 host: localhost:3000 schemes: - http securityDefinitions: ApiKeyAuth: type: apiKey in: header name: X-API-Key paths: /secure-data: get: summary: Geschützte Daten abrufen security: - ApiKeyAuth: [] responses: '200': description: Erfolgreiche Antwort schema: type: object properties: data: type: string OAuth 2.0 Authentifizierung Eine moderne und flexible Methode zur Authentifizierung ist OAuth 2.0. Damit können sich Nutzer sicher bei der API authentifizieren. securityDefinitions: OAuth2: type: oauth2 flow: accessCode authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Zugriff auf geschützte Ressourcen paths: /user-info: get: summary: Benutzerinformationen abrufen security: - OAuth2: - read responses: '200': description: Erfolgreiche Antwort schema: type: object properties: username: type: string Hier wird sichergestellt, dass der Endpunkt /user-info nur für authentifizierte Nutzer mit dem entsprechenden OAuth2-Token zugänglich ist. Der Scope read erlaubt es Nutzern, auf geschützte Ressourcen lesend zuzugreifen, ohne Änderungen vorzunehmen. Dies eignet sich für Endpunkte, die sensible, aber unveränderbare Informationen bereitstellen, wie z. B. Profildaten oder Systemstatus. Ein Beispiel für eine API, die mit einem API-Key geschützt ist: swagger: '2.0' info: title: Geschützte API version: 1.0.0 host: localhost:3000 schemes: - http securityDefinitions: ApiKeyAuth: type: apiKey in: header name: X-API-Key paths: /secure-data: get: summary: Geschützte Daten abrufen security: - ApiKeyAuth: [] responses: '200': description: Erfolgreiche Antwort schema: type: object properties: data: type: string Best Practices für eine gut strukturierte API-Dokumentation Um eine API-Dokumentation optimal zu gestalten, sollten einige Best Practices beachtet werden: Konsistente Struktur: Eine gut organisierte API-Dokumentation erleichtert das Verständnis und sorgt für eine einheitliche Dokumentation aller Endpunkte. Dies kann in Form von API Design Guidelines zusammengefasst werden, die unter anderem Konventionen für Namensgebung, Versionierung und Sicherheitsaspekte festlegen. Aussagekräftige Beschreibungen: Jeder Endpunkt sollte detaillierte Beschreibungen enthalten, damit Nutzer sofort erkennen, wie er funktioniert. Beispielsweise könnte der Endpunkt /users mit der Beschreibung Gibt eine Liste aller registrierten Benutzer zurück. Optional kann über einen Query-Parameter nach bestimmten Namen gefiltert werden. versehen werden. Dies hilft Entwicklern, den Zweck und die möglichen Einsatzmöglichkeiten des Endpunkts besser zu verstehen. Beispieldaten bereitstellen: Durch die Verwendung von example oder examples kann ein realistischer Eindruck der API-Antworten vermittelt werden. Beispielsweise könnte ein Endpunkt, der Benutzerinformationen zurückliefert, eine Beispielantwort mit id: 1 und name: 'Max Mustermann' enthalten, um den erwarteten Datenaufbau zu verdeutlichen. Authentifizierung angeben: Falls eine Authentifizierung erforderlich ist, sollte diese klar dokumentiert werden, z. B. durch die Verwendung von API-Keys oder OAuth. API-Keys sind einfach zu implementieren und eignen sich gut für serverseitige Anwendungen, können jedoch unsicher sein, wenn sie in Clients offengelegt werden. OAuth bietet ein sichereres Authentifizierungsverfahren mit Token-basiertem Zugriff, ist jedoch komplexer in der Implementierung und erfordert zusätzliche Infrastruktur wie einen Autorisierungsserver. Versionskontrolle: Eine API entwickelt sich weiter. Durch klare Versionskennzeichnungen kann sichergestellt werden, dass Nutzer immer die richtige Dokumentation verwenden. Zum Beispiel kann eine API-Version in der URL definiert werden (/v1/users) oder durch das info.version-Attribut in Swagger (version: '1.0.0'). Dies hilft, ältere Versionen zu unterstützen und neue Features schrittweise einzuführen. Die Verwendung des Semantic Versioning (SemVer) Ansatzes (MAJOR.MINOR.PATCH) ermöglicht es Entwicklern, Änderungen transparent zu kommunizieren, indem beispielsweise eine Erhöhung der Major-Version (v2.0.0) auf inkompatible Änderungen hinweist, während Minor-Updates (v1.1.0) neue Funktionen ohne Breaking Changes hinzufügen. Wiederverwendbare Komponenten nutzen: Häufig verwendete Elemente wie Schemas, Parameter oder Antworten sollten in definitions (Swagger 2.0) gespeichert werden. Dadurch wird die API-Dokumentation konsistenter und leichter wartbar. Swagger erlaubt verschiedene Definitionstypen, darunter definitions für Datenmodelle, parameters für wiederverwendbare Parameter, responses für vordefinierte API-Antworten und securityDefinitions zur Authentifizierung. Beispielsweise kann eine Benutzerstruktur einmalig definiert und mehrfach referenziert werden: $ref: '/definitions/User'. Interaktive Swagger UI nutzen: Eine interaktive Dokumentation erleichtert Entwicklern das Testen der API und reduziert den Kommunikationsaufwand. Fazit Mit diesen Schritten und bewährten Methoden gelingt eine professionelle API-Dokumentation mit Swagger 2.0. Eine gepflegte und gut strukturierte API-Dokumentation erleichtert nicht nur Entwicklern die Implementierung, sondern verbessert auch die Zusammenarbeit mit anderen Teams, fördert die Wartbarkeit und erhöht die Transparenz der API-Nutzung. Eine gut strukturierte Dokumentation ist ein essenzieller Bestandteil jeder API-Entwicklung, da sie nicht nur Entwicklern hilft, sondern auch die Zusammenarbeit in Teams verbessert.

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.