Das Dokument behandelt den Ansatz des API-First-Designs unter Verwendung von Swagger/OpenAPI, um branchenneutrale Softwareentwicklung und IT-Beratung zu fördern. Es werden Beispiele und Anwendungsfälle für das Bestellen von Kaffee über eine API vorgestellt, sowie die notwendigen Schritte und Ressourcen zur Umsetzung eines API-First-Ansatzes erläutert. Zudem werden Tools und Methoden zur Dokumentation, Validierung und Integration von APIs aufgezeigt.

1. #WISSENTEILEN
@_openKnowledge
API-First
Design mit
API-First Design
mit Swagger/OAS

2. BRANCHENNEUTRALE SOFTWAREENTWICKLUNG UND IT-BERATUNG
ÜBER OPEN KNOWLEDGE

3. ÜBER UNS
Wer bin ich - und wenn ja, wie viele?
• Enterprise Architect
• Enterprise & mehr
• Autor, Speaker, Berater, Coach
• Tauch & Ski Enthusiast
• Grillmeister & Hobbygärtner ;)
STEPHAN MÜLLER
SM

4. #WISSENTEILEN
APIbucks
... ordering Coffee the digital way

5. #WISSENTEILEN
„Order 123 for
‚Larissa‘.“
„And here‘s the
receipt.“
„Here‘s 5$.“
„What‘s the
status of ‚123‘?“„Still preparing.“
„Now its ready.“
API-First Design mit Swagger/OAS by Example
{?} „Coffee, latte,
large, to-go,
semi, double
shot, please.“

6. #WISSENTEILEN
place an ORDER (UC-01)
customize the ORDER (UC-02)
pay for ORDER (UC-03)
check status of ORDER (UC-04)
add ORDER
to queue
deliver ORDER
API-First Design mit Swagger/OAS by Example
{?}

7. #WISSENTEILEN
{A}1ST

8. #WISSENTEILEN
YOUR API IS THE
FIRST USER
INTERFACE OF
YOUR APPLICATION

9. #WISSENTEILEN
YOUR API COMES
FIRST, THEN THE
IMPLEMENTATION

10. #WISSENTEILEN
YOUR API IS
DESCRIBED (AND
MABY EVEN
SELF-DESCRIPTIVE)

11. #WISSENTEILEN
API-First!
#1 – Planen
#2 – Entwerfen & Validieren
#3 – Überarbeiten
#4 – Testen
#5 – Implementieren
#6 – Betreiben & Lernen (zurück zu #1)
API-First Design mit Swagger/OAS by Example
{?}

12. #WISSENTEILEN
Was brauchen wir zur Umsetzung?
• Repräsentation der Order (JSON, XML, ...)
• Kommunikation zwischen Client & Service (HTTP)
• den Service selbst als Ressource (URI)
• und … (z.B. custom Header)
{?}
API-First Design mit Swagger/OAS by Example

13. #WISSENTEILEN
APIbucks
... API-First – Round 1

14. #WISSENTEILEN
// UC-01 order coffee
// UC-02 change order
// UC-03 pay order
// UC-04 check order status
APIbucks

15. #WISSENTEILEN
// UC-01 order coffee
POST /orders
{ ... initial order data ... }
// UC-02 change order
PUT /orders/1234
{ ... some changes ... }
// UC-03 pay order
POST /payments
{ ... payment data & order id ... }
// UC-04 check order status
GET /orders/1234
APIbucks

16. #WISSENTEILEN
Swagger / Open API Specification (OAS)
API-First Design mit Swagger/OAS by Example
Design mit Swagger Editor Build mit Swagger Codegen Dokumentiere mit Swagger-UI

17. #WISSENTEILEN
Swagger / Open API Specification (OAS)
API-First Design mit Swagger/OAS by Example
Teste mit Postman Integriere alles mit SWAGGERhub

18. #WISSENTEILEN
3rd Party Tools mit Swagger/OAS Unterstützung
• Dokumentiere mit ReDoc & Asciidoc
• Prüfe Consumer-driven Contracts mit Pact
• Implementiere client-seitige Validierung auf Basis von JSON-
Schema
API-First Design mit Swagger/OAS by Example

19. #WISSENTEILEN
demo$ demo
demo$ api-first design
demo$ |

20. #WISSENTEILEN
„Das* API ist das
UI des Entwicklers.“
(*wer möchte, darf auch “die API“ sagen)

21. #WISSENTEILEN
FRAGEN
? ? ?

22. Kontakt
STEPHAN MÜLLER
ENTERPRISE ARCHITECT
stephan.mueller@openknowledge.de
+49 (0)441 4082 – 0
@_openknowledge
OFFENKUNDIGGUT
#WISSENTEILEN

23. Bildnachweise
#01: © dzone.com
#16: © swagger.io
#17: © swaggerhub.com, getpostman.com
All other pictures inside this presentation orginate
from pixabay.com or were created by my own.
#WISSENTEILEN