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

Die API wurde in Produktion deployed
Es gibt eine offizielle Dokumentation zu Nutzung und Einbindung
Die API wurde in den offiziellen API-Katalog übernommen
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 -
Vorhersehbar

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

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?

Inception	Choice generation	Choice selection	Authorization	Implementation	Challenge
Decentralized	Decentralized	Decentralized	Decentralized	Decentralized	Decentralized

Decision Mapping

Programming Language

Inception	Choice generation	Choice selection	Authorization	Implementation	Challenge
Decentralized	Decentralized	Decentralized	Decentralized	Decentralized	Decentralized

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

API Design

API Design

More from Johann-Peter Hartmann