Create-Stage einer API:
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.
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.
Any change to an API MUST NOT break existing clients. Any change to:
Resource identifier (resource name / URI) including any query parameters and their semantics
Resource metadata (e.g. HTTP headers)
Action the resource affords (e.g. available HTTP Methods)
Relation with other resources (e.g Links)
Representation format (e.g. HTTP request and response bodies)
MUST follow the API Extension Rules
Mark as Depreprecated
Inform Users
Remove Documentation of the deprecated interface
Grace Period & Final notice
Interface entfernen
*
*
*
*
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?
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?
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?
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?
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?
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?
vs
Don't use acronyms
Use camelCase unless stated otherwise
Reconcile terms with Ubiquituous Langauge
ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV
GET /User/Preferences/Address/Private
GET /User/Preferences/Address/Private
GET /User/Preferences/Address/Private
GET /User/Preferences/Address/Private
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
MAJOR.MINOR.PATCH
Where the version goes
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
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!
Inception | Choice generation | Choice selection | Authorization | Implementation | Challenge |
---|---|---|---|---|---|
Decentralized | Decentralized | Decentralized | Decentralized | Decentralized | Decentralized |
Inception | Choice generation | Choice selection | Authorization | Implementation | Challenge |
---|---|---|---|---|---|
Decentralized | Decentralized | Decentralized | Decentralized | Decentralized | Decentralized |
Hmm, das wird dann ganz schön kommunikativ. Und fremdbestimmt. Und langsam.