In den vergangen Jahren entstand eine API-Industrie für zunächst E-Commerce dann auch für soziale Medien, Cloud, Mobile und Internet der Dinge. Die Anzahl der Web APIs wächst sehr schnell durch unzählige Unternehmen, deren Hauptprodukte Web APIs sind. Dieser Vortrag beschreibt die Entwicklung dieser API-Industrie anhand einiger Beispiele und geht dann konkret auf die Themen Versionierung und Dokumentation ein.

1. 16.03.2015
API-Industrie
Kai Spichale
adesso AG

2. Klassische Funktionen einer API
2
Client API Implementation
Entkopplung von
Implementierung
Definiert Komponente
durch ihre Operationen
mit Ein- und
Ausgabewerten
Software-
wiederverwendung
und Integration

3. Kommunikationsproblem bei
Softwarewiederverwendung
Lösung: Kommunikation durch API
> APIs werden für Menschen geschrieben
> Perspektive ist beim API-Design entscheidend
3
?

4. Wirtschaftliche Gründe für eine API
4
Mobile Strategie
Benutzung einer
Plattform
antreiben
Investition in
neuen
Geschäftszweig
Integration
► Viele unterschiedliche Geräte
► Skalierbarkeit
► Twitter steigerte Traffic durch
gute API
► z.B.: Best Buy steigerte Online-
Handel
► Innerhalb eines Unternehmens
u. mit Partnern
► z.B.: FedEx-kompatible
Applikationen

5. Treiber der API-Industrie
► E-Commerce
► Soziale Medien
► Cloud
► Mobile
► Internet der Dinge
5
Smart Home

6. Zunahme von Web APIs seit 2005
0
2000
4000
6000
8000
10000
12000
14000
Jun/ 05 Okt/ 06 Dez/ 07 Feb/ 09 Apr/ 10 Jun/ 11 Aug/ 12 Okt/ 13
6
Quelle: http://www.programmableweb.com/api-research (17.02.2015)

7. API als Produkt
7

8. Bedeutung einer API für ein Unternehmen
8
Wertvollstes
Asset
Größte
Verbindlichkeit
► Schwer änderbar
► Produktreife ist entscheidend

9. Produktreife
► Feature Completeness
► Application Lifecycle Managment
► Application Management Support
► Versionierung
► Dokumentation
► Sicherheit
► Qualitätssicherung
► …
9

10. Eine Auswahl ..
10

11. Spezifikation u. Dokumentation
11

12. Spezifikation u. Dokumentation
12
Zielgruppe Beispiele Versionierung

13. (Menschenlesbare) Dokumentation
► API Guide (Anwendungsfälle)
► API Referenz (Endpoints, HTTP-Methoden, Formate, ..)
► Installations- und Betriebshandbuch
► Release-Notes
► Upgrade-Pfade für versionierte APIs
13

14. Spezifikation
► Design-time Beschreibungssprachen:
> Swagger (Reverb)
> RAML (Mulesoft)
> API Blueprint (apiary.io)
> ioDocs (Mashary)
> WADL (org. von Sun Microsystems)
> …
► Bieten Mehrwert in Verbindung mit jeweiliger Plattform
14

15. Selbstbeschreibende Hypermedia-APIs
► Einstiegs-URI
► Zustandsänderung gesteuert durch Client mithilfe von Links,
bereitgestellt vom Server
► Standardisierte MIME-Types
> Collection+JSON
> Siren
> HAL
> …
15

16. Profiles
► Bieten zusätzliche semantische Erklärungen für
„applikationsagnostische” MIME-Types
► Keine Änderung der existierenden Bedeutung der
Ressourcenrepräsentation
► Beispiel: Application-Level Profile Semantics (ALPS)
16

17. Versionierung
17

18. Versionierung mit Query-Parameter
http://api.example.com/orders?version=v1
Hinweis:
► Schlechter Stil: HTTP bietet bessere Mechanismen
► Query-Parameter geeignet zum Filtern, Suchen und
Sortieren
18

19. Versionierung mit URI
http://api.example.com/[version]/orders
http://api.example.com/orders/[version]
Vorteile:
► Verständlich, offensichtlich
► Auch Permalinks von alten Clients werden nicht gebrochen,
wenn diese bereits versionierte URIs nutzen
Hinweis:
► Kein RESTful HTTP
19

20. Versionierung mit Content Negotiation
GET /orders HTTP/1.1
Host: api.example.com
Accept: text/html, application/xhtml+xml,
application/xml;q0.9, */*;q=0.8
20

21. Versionierung mit Content Negotiation
GET /orders HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1.orders+json
Vorteile:
► Im Einklang mit RESTful HTTP
► Client entscheidet über das Format
21

22. ► Unterstützung verschiedener Formate (XML,
JSON, HTML)
► Browser-Konfiguration:
Accept: application/xml, application/xhtml+xml,
text/html;q=0.9, text/plain;q=0.8,
image/png, */*;q=0.5
► Ergebnis: Browser erhält Tweets als XML :-(
22

23. 23
► Lösung des Browser-Problems:
https://userstream.twitter.com/1.1/user.json
https://api.twitter.com/1.1/search/tweets.json
Zum Vergleich:
http://farm3.static.flickr.com/123456789.jpg

24. Architektur
API-Gateway
24

25. Komplexität durch Versionierung und
Erweiterungen
25
Client-
Gruppe 1
Monolith mit hoher Komplexität
API v1
Client-
Gruppe 2
API v2
Client-
Gruppe 3
API v3

26. Produkt v2
Alternative Microservice-Architektur
26
Client-
Gruppe 1
Produkt v1
API v1
Client-
Gruppe 2
API v2
Client-
Gruppe 3
Produkt v3
API v3

27. API Gateway: Mehr als Lastverteilung
27
Client-
Gruppe 1
Client-
Gruppe 2
Client-
Gruppe 3
API-Gateway
Config
Produkt v2Produkt v1
API v1 API v2
Produkt v3
API v3

28. Kai Spichale
@kspichale
http://spichale.blogspot.de/
https://www.xing.com/profile/Kai_Spichale
28