API Design mit REST & Swagger

Schulung / Webinar

Gutes Design trägt dazu bei, dass ein API einfach und intuitiv genutzt werden kann. Im Gegensatz zur Nutzung ist der Entwurf einer eleganten und schlanken Schnittstelle recht aufwendig und erfordert einiges an Erfahrung. Dieses Seminar richtet sich an Entwickler und API Designer, die das API Design Handwerk erlernen und perfektionieren möchten.

In der Schulung werden u.a. die folgenden Fragen beantwortet:

  • Wie muss ein API gestaltet sein, damit es einfach und intuitiv zu verwenden ist?
  • Wie gehe ich beim API Design Prozess vor?
  • Welche Spezifikationen und Werkzeuge unterstützen das API Design? Und wie sinnvoll und akzeptiert sind diese?
  • Wie erweitere und verändere ich ein API damit es zu früheren Versionen kompatibel bleibt?
  • Welche Firmen, Werkzeuge und Spezifikationen weisen der Branche den Weg?
  • Wie vermeide ich Stolperfallen?

Lerne von den Großen des Webs: wie gestalten Google, Facebook, Netflix und Twitter Ihre APIs? Übernehme Muster und Best Practise Ansätze für Deine eigenen API Projekte.

In zahlreichen Übungen arbeitest du selbst am API Design und verwendest dabei nützliche Werkzeuge.

API Einführung

  • Was ist ein API?
  • Wie unterscheidet sich ein API von Web Services und RPC
  • Von REST Puristen und Pragmatikern
  • Der API Lifecycle
  • Die REST Prinzipien: Adressierbarkeit, Repräsentationen, Uniform Interface, Statuslosigkeit, ...

Ressource & URI Design

  • Was sind Ressourcen?
  • Wie modelliere ich Ressourcen?
  • Container- und Subressourcen
  • Wie unterscheiden sich URL und URI
  • Aufbau und Struktur einer URI
  • Bestimmen des API Entrypoints
  • URI Templates, RFC 6570
  • Welche Art von Id verwende ich für URIs?

Parameter

  • Query-, Path-, Header-, Body- und Matrix-Parameter
  • Für was setzte ich welche Art von Parameter ein?
  • Formate für Datum- und Uhrzeit

Suchen, Filtern & Sortieren

  • Blättern
  • Filtern nach Typ, Feldname

HTTP Methoden

  • Überlick zu GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, TRACE
  • PATCH versus PUT
  • Idempotenz

Formate

  • XML, YAML oder JSON oder?
  • Der richtige Content-Type
  • Content Negotiation: Wie Client und Server das Format aushandlen
  • JSON API

JSON Design

  • Struktur von JSON Nachrichten
  • Datentypen in der Übersicht
  • JSON Schema
  • Envelope für Daten?
  • JSON Abfragen: JSONPath, JSON Pointer und Reference

Versionierung

  • Evolution oder Revolution?
  • Semantic Versioning
  • Wohin mit der Versionsnummer?
  • Das Tolerant Reader Pattern
  • Welche Änderungen eines APIs brechen das Interface?
  • Versionierung von JSON, XML und anderen Formaten

Fehlerbehandlung

  • Fehlerarten
  • Beschreibung von Fehlern
  • Status Codes: 4XX, 5XX
  • Fehlermeldungen

REST Design Patterns

  • Idempotent Capability
  • Optimistic Locking mit REST anstatt Transaktionen
  • Metadaten

API Design Prozess

  • Wie gehe ich beim API Design vor?
  • API Mocking

Guidelines & Richtlinien

  • Namenskonventionen und Schreibweisen
  • Erstellen von eigenen Guidelines oder Übernahme von bestehenden Guidelines?
  • Beispiele für gute API Style Guides

Hypermedia und HATEOAS

  • RESTful Web Services mit Hypertext & Hypermedia
  • Beziehungen mit Bedeutung: Semantic Relationships
  • Link Formate: HAL, JSON-LD oder Web Linking?
  • Navigation und Pagination
  • URI Übergabe im Link Header
  • Vor- und Nachteile von HATEOAS

API Beschreibung & Dokumentation

  • Formate zur API Beschreibung im Überblick: API Blueprint, RAML, Swagger und WADL
  • Automatisches Erzeugen von Dokumentation
  • Service Life Cycle und API Description
  • Code Generierung aus API Spezifikationen
  • Wie dokumentiere und beschreibe ich meine Ressourcen am besten?
  • Dokumentation und generische Clients aus Metadaten erzeugen
  • Beispiele mit curl

Swagger bzw. Open API

  • Erkunden und Testen eines API mit der Swagger UI
  • Beschreibung eines REST API mit dem Swagger Editor
  • Contract First: Erzeugen von Client- und Servercode aus Swagger
  • Generierung von Swagger Spezifikationen aus bestehendem Code
  • Swagger-Unterstützung von Werkzeugen und Frameworks
  • Erstellen eines Test Mock
  • Neues in Open API Version 3

Qualitätssicherung

  • Überprüfen von Open API Dokumenten
  • Automatische Analyse von API Beschreibungen
  • Design Beurteilung und Überprüfungw

API Discovery

  • Finden von Services und Resourcen
  • API Repository, Notebook u. Directory
  • Verwaltung von API Definitionen
  • Ausblick API Mangement

Caching

  • Zeit- oder Inhaltsbasiert?
  • Bedingte Abfragen mit: Last-Modified, If-Modified-Since und ETag Header

API Security

  • OAuth 2
  • HTTP Header 401, 403, 405
  • Reverse API Proxies und API Gateways

REST Antipatterns

  • RPC-like Interfaces
  • CRUDy Interface
  • HTTP Tunnel
  • Auswirkungen des REST Designs auf die Performanz
  • Chatty oder Chunky

Ziele

  • Für was eignet sich REST und wann nehme ich vielleicht besser GraphQL?
  • Abfragen und Filter mit GraphQL
  • Manipulation mit GraphQL: Anlegen, Löschen und Verändern

API Design Markübersicht (Optional)

  • Welche Player gibt es auf dem Markt und wie positionieren sich diese?
  • Die API Player im Überblick: 3Scale, Apiary, Apigee, Apimatic, Mulesoft, Mashape
  • Was sind die aktuellen API Design Trends?
  • Produkte und Spezifikationen im Überblick
  • Die Tools: API Editoren, Repositories, Validatoren

Deine Vorteile

  • Du lernst wie Du elegante REST APIs entwerfen kannst, die einfach zu verwenden sind

Dauer

2 Tag

Zielgruppe

API Designer, Software Architekten, Web Entwickler und Programmierer

Vorkenntnisse

REST Grundlagen wie sie im Seminar REST Web Services vermittelt werden

Kursunterlage

Handouts aller in der Schulung präsentierten Folien.

APIRESTSwaggerSchulungDesign