API Design

Tunnel Style APIs

Ressource Style

Hypermedia Style

Query Style

Event Style

API Lifecycles

1. Create

Create-Stage einer API: 

• es ist eine neue API oder ein Ersatz für eine API die es nicht mehr gibt
• sie ist noch nicht in Produktion
• sie wurde noch nicht für andere für den Normalbetrieb verfügbar gemacht

1. Create

2. Publish

1. Die API wurde in Produktion deployed
2. Es gibt eine offizielle Dokumentation zu Nutzung und Einbindung
3. Die API wurde in den offiziellen API-Katalog übernommen
4. Alle wurden informiert, wie und wo sie die API jetzt nutzen können

2. Publish
API User Stories

3. Realize

• Eine publizierte API existiert und ist einsetzbar
• sie wird produktiv eingesetzt 
• ... und ist dabei wirklich nutzenstiftend
• sobald man was kaputt macht haben andere Leute echte Probleme

4. Maintain

• Die API wird aktiv eingesetzt von >=1 Parteien konsumiert
• die Nutzung ist stabil oder wird weniger 
• man optimiert nicht aktiv an der API

5. Retire

• eine publizierte API existiert und ist verfügbar
• es lohnt sich nicht mehr, sie zu maintainen
• es gibt ein Ablaufdatum 

Worum kümmern? 

1. Create

• Initiale Strategie festlegen
• Feasibility-Evaluation und Test
• Strategieanpassung auf Basis von Feasibility

1. Strategy

• Initiale Strategie festlegen
• Feasibility-Evaluation und Test
• Strategieanpassung auf Basis von Feasibility

2. Design

• Design des API Interaces
• Test des API designs durch Nutzer
• Validierung der Implementierung des Interfaces

API First

API design (e.g., description, schema) is the master of truth, not the API implementation.

API implementation MUST always be compliant to particular API design which represents the contract between API, and it's consumer.

API Contract

Approved API Design, represented by its API Description or schema, MUST represent the contract between API stakeholder, implementers, and consumers.

An update to the corresponding contract (API Design) MUST be implemented and approved before any change to an API.

3. Development

• Skelett entwickeln
• Interfacetests bereitstellen
• Initiale Implementierung der API-Funktionalität

4. Deployment

• Dev-Setup der API bereitstellen
• Tests für die Kollegen bereitstellen
• Test & Integrations-Deploy bereitstellen

5. Documentation

• OpenAPI-Dokumentation
• Tutorial
• Offizielles API-Verzeichnis

6. Testing

• Arten von Tests definieren
  • Load 
  • Security
  • Integrations...
• Tests implementieren 
• Testplatform integrieren

7. Security

• Security-Requirements festlegen
• Definiertes Interface auf Security prüfen
• Security-Automatisierung einrichten

8. Monitoring

• Business-KPIs der API definieren
• System-KPIs der API definieren
• Ins Monitoring integrieren

9. Discovery

• Ist das Verhalten wie geplant? 
• Ist es für die Nutzer effizient? 
• Was muss sich ändern? 

10. Change Management

• eine Struktur für Changes bereitstellen
• Diese Struktur kommunizieren
• Diese Struktur umsetzen

API Changes

• Any change to an API MUST NOT break existing clients. Any change to:

  1. Resource identifier (resource name / URI) including any query parameters and their semantics

  2. Resource metadata (e.g. HTTP headers)

  3. Action the resource affords (e.g. available HTTP Methods)

  4. Relation with other resources (e.g Links)

Representation format (e.g. HTTP request and response bodies)

MUST follow the API Extension Rules

API Changes

• Mark as Depreprecated

• Inform Users

• Remove Documentation of the deprecated interface

• Grace Period & Final notice

• Interface entfernen

Entscheidungen

*

*

*

*

Decisions ...

Inception:

Bemerken, dass man eine Entscheidung braucht.
Wer macht das? Passiert das rechtzeitig? Was geht implizit, was muss explizit sein? Haben wir alle impliziten Entscheidungen bemerkt? 

Decisions ...

Choice Generation:

Feststellen, welche Optionen eine Rolle spielen sollten.

Kennen wir alle relevanten Optionen? Haben wir Erfahrungswerte und externe Daten für die Optionen? Welche Optionen passen in die aktuelle Applikationslandschaft, welche nicht?

Decisions ...

Selection:
Eine der Optionen auswählen.

Wie bewerten wir die Optionen gegeneinander? Welche Aspekte müssen wir und wollen wir dabei berücksichtigen? Welche Priorität hat welcher Aspekt? 

Decisions ...

Authorization:
Die gewählte Option authorisieren.

Muss die Option implizit oder explizit bestätigt werden? Wer muss die Entscheidung kennen, wer muss auf Feasibility / Showstopper prüfen? Wie macht man das?

Decisions ...

Implementation:
Die Entscheidung wirksam machen.

Wer muss informiert werden? Wo muss die Entscheidung dokumentiert werden? Welches Wissen muss vorher aufgebaut werden? Wie findet die Entscheidung in den Backlog? 

Decisions ...

Challenge:
Probleme oder neue Alternativen erkennen und damit umgehen.

Was ist der Alternativpfad, wenn ein Team mit der Entscheidung nicht arbeiten kann? Wenn eine neue, bessere Lösung existiert? Wenn die Kosten des Umbaus die Integration deutlich übersteigen würden?

Decisions ...

Gute APIs -
Expressiv

• handleObject
• /v1/entity/12
• messaging_topic

vs 

• /account/...
• /UserPreferences

Gute APIs -
Simple

Gute APIs -
Simple

Gute APIs -
Vorhersehbar

• firstName vs FirstName vs first_name vs first-name vs First-Name
• /book vs /books
• /buch vs /book

Gute APIs -
Ubiquituous Language

Gute APIs -
Ubiquituous Language

Gute APIs -
Ubiquituous Language

API Naming Rules

• Use American English

• Don't use acronyms

• Use camelCase unless stated otherwise

• Reconcile terms with Ubiquituous Langauge

Gute APIs -
IDs

• easy to use (überschaubar groß, keine "/" im Namen)
• unique - /user/lhartmann & /user/3-reusage
• permanent - /user/hartmann-stein vs /user/hartmann
  • != E-Mail
• fast & easy to generate - man muss nicht prüfen, ob die ID schon vergeben ist 
• unpredictable - keine Enumeration
• readable - kein 11IIllOO00
• shareable - Copy-Paste über Codepages hinweg
• verifiable - es ist erkennbar, wenn Teile fehlen
• information dense - keine 2048 Bit für diesen Planeten

Gute APIs -
IDs - ulid statt UUID

ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV

• 128-bit compatibility with UUID
• 1.21e+24 unique ULIDs per millisecond
• Lexicographically sortable!
• Canonically encoded as a 26 character string, as opposed to the 36 character UUID
• Uses Crockford's base32 for better efficiency and readability (5 bits per character)
• Case insensitive
• No special characters (URL safe)
• Monotonic sort order (correctly detects and handles the same millisecond)

Antipattern -
Hierarchie

GET /User/Preferences/Address/Private

Antipattern -
Hierarchie

GET /User/Preferences/Address/Private

Antipattern -
Hierarchie

GET /User/Preferences/Address/Private

Antipattern -
Hierarchie

GET /User/Preferences/Address/Private

Antipattern -
Resources for Everything

Antipattern -
Deep Hierarchy

Antipattern -
Inline Everything

V1: Variety

• Nur REST?
• REST und Events in Kafka?
• REST und Events und GraphQL?
• REST und Events und GraphQL und existierende APIs?
• Was auch immer das Team will
   
•    (die armen   Schweine, die das nutzen müssen)

V2: Vocabulary

• API-Naming: Pfad, Singular/Plural
• IDs & ID-Typen
• "Enterprise Information Model"/Ubiquituous Language
• HTTP: Status-Codes, Content Types, Cache Directives, Encodings
• JSON-Fehler (RFC7807)

API Counts

Zalando:
a typical range of resources for a well-designed API ist between 4 & 8
 

Adidas: 

Every API design MUST aim for a minimal API surface without sacrificing on product requirements. API design SHOULD NOT include unnecessary resources, relations, actions or data. API design SHOULD NOT add functionality until deemed necessary

V3: Volume

• Anzahl Calls durch andere APIs
• Wie weit skaliert meine API
• Und wie weit muss dann Deine API skalieren?

V4: Velocity

• Wie gehen wir mit Änderungen um?
• Lead Time für API-Änderungen
• Lead Time für neue APIs
• Tests und API-Rollbacks
• Consumer-Driven-Contracts

API Extending

• Es darf nichts aus APIs entfernt werden
• Die Regeln zu Integration und Nutzung dürfen sich nicht ändern
• Optionale Parameter dürfen nicht required werden
• Alles was ergänzt wird muss optional sein.

V5: Vulnerability

• Welche APIs sind extern sichtbar? 
• Welche APIs brauchen Rechte?
• Welche Rechte werden weitergegeben?
• Welchen Security-Standards möchte man haben?
• Wo darf man bei Ausfall mit einem gecachtem Wert arbeiten?
• Welche Nachvollziehbarkeit braucht man?

V6: Visibility

• Wie finde ich alle aktuellen APIs? 
• Wie finde ich die Beschreibung aller APIs?
• Wie finde ich die Änderungen? 
• Wie finde ich die technische Beschreibung?

V7: Versioning

• Versioniere ich überhaupt?
• Wie versioniere ich?
  • /apiv2 vs semantic versioning
• Wo finde ich die Version in der Software?
• Wo finde ich die Version in der Kommunikation?
• Wie sind die Versionen dokumentiert?

Semantic Versioning 

MAJOR.MINOR.PATCH

• MAJOR: breaking Changes. Client _muss_ geändert werden.
• MINOR: Neue Funktionalität. Änderung im Client nur für Featurenutzung erforderlich.
• PATCH: Bug fixes. Gleiche Funktionalität, Clients machen nichts.

Header Versioning 

Where the version goes

• PATH - Evolving standard
  http://example.com/api/1/products
• PARAMETER
  http://example.com/api/products?version=1
• HEADERS
  curl -H “Accepts-version: 1.0” http://example.com/api/products
• NEGOTIATION
  curl -H “Accept: application/vnd.xm.device+json; version=1”
   

V8: Volatility

• Wie oft zerbricht meine API etwas? 
• Wie sehr wirkt sich die Velocity in Problemen aus?
• Wie weit trägt Komplexität zu Fehlern bei?
• Wie oft trägt fehlende Qualität zu Fehlern bei?

Postel's LAW

Postels Law / Robustness Principle:

be conservative in what you send, be liberal in what you accept.

Adidas: 

Every API design MUST aim for a minimal API surface without sacrificing on product requirements. API design SHOULD NOT include unnecessary resources, relations, actions or data. API design SHOULD NOT add functionality until deemed necessary

Loose Coupling

API consumers (clients) MUST operate independently on API implementation's internals. Similarly the API consumers MUST NOT assume or rely on any knowledge of the API service internal implementation.

Where available, the clients SHOULD utilize hypermedia controls as the engine of the application state, and rely on the protocol, message and vocabulary semantics.

Links statt IDs!

Ok, und wie mache ich das konkret?
Pattern :-)

Role: API Product Manager

• Product Owner für die API
• Spricht mit den API-Consumern
• Dokumentiert die API-User-Stories
• Sorgt für die nonfunktionalen Anforderungen
  • Monitoring
  • Security etc
• Verantwortlich für Developer Experience
  (Design, Onboarding, ongoing Relationship)

Role: API Designer

• Designed das Interface auf Basis der API User Stories
• Implementiert die nonfunktionalen Anforderungen
• Stellt es im ALM zur Verfügung: Dev, Test, CI, Produktion
• Ansprechpartner für Nutzer der API
• Alignment zu Company Guidelines

Role: API Technical Writer

• Technische Dokumentation
• Zentrale Dokumentation
• Tutorials zur Nutzung
• Aktualisierung der Doku

Role: API Engineer and Architect

• Lead Engineer:
  • Entscheidet über das How der API
  • Konkret: Development, Monitoring, Deploy
• Architect: 
  • Integriert die API in die API-Landscape 
  • Konsistenz mit Standards
  • Konsistenz mit nonfunktionalen Anforderungen

Role: API Developer

• Frontend Developer
  • Implementiert die Schnittstelle
  • Fokus auf Consumer Experience
  • Integration in API registry, Consumer Portal, Swagger etc
• Backend Developer: 
  • Implementiert die Funktionalität
  • Persistenz
  • Implementierung der nonfunktionalen Anforderungen

Role: API Evangelist

• Stellt sicher, dass alle von der API wissen
• Sammeln Feedback von den API Consumern ein
• Bieten Trainings, Demos etc an

Monolith is easy ...

... but MicroServices?

Decision Mapping

Programming Language

API Decisions

• /login /account /user /users /usercollection
• Header vs other Header vs Path vs Host-Versioning
• Versioning: simple vs semanitic 
• Entity Naming: team vs company wide
• Id Naming

Highway to Hell

Also alles zentral?

Hmm, das wird dann ganz schön kommunikativ. Und fremdbestimmt. Und langsam.

Dezentralisierung heißt nicht Chaos

Guidance

• Why: Warum gibt es diese Empfehlung, was würde passieren, wenn man sie nicht trifft?
   
• What: Welcher Ansatz wird empfohlen, wie löst er die Anforderungen?
   
• How: Wie wendet man ihn selbst konkret an.

Design Authority

• Minimalanforderungen pflegen und dokumentieren
• Team für Standards, Training & Coaching
• Gatekeeper für APIs & API-Änderungen
• Incentivieren von guten APIs
• Vorteile: Standards! Verlässlichkeit!
• Nachteile: Engpass by Default, Implementierungsfern

Embedded Centralized Experts 

• Gremium aus Experten aus den Teams
• Enforcement und Incentivierung ist direkt in den Teams
• Knowhow und Training passiert direkt in den Teams
• Vorteile: Nähe zum Operativen
• Nachteile: Gremienarbeit und Meetings

Influenced Self-Governance

• "Golden Path" - Set von empfohlenen, State of the Art tools 
• Kombination von "blessed" Tools, Tutorials, Templates und unterstützung
• für jeden Bereich ein Set
• Vorteile: Standards sind locking-frei, attraktiv und freiwillig
• Nachteile: keine Verbindlichkeit, lokale Optima, Bereitstellungskosten

Vorgehen über Zeit

• Early Stage
  detaillierte Guidelines & klare Rollen
• Middle Stage
  Lifecycle Empfehlungen fürs Vorgehen für Design, Implementierung, Interaktionen und Versionierung
• Later Stage
  Big picture - market place and ecosystem guidelines

Worum kümmern?