Design First APIs
Juri Leino
e-editiones.org | exist-db.org
Declarative Amsterdam 2025
What is an API anyway?
Human
Machine
A contract between servers and clients
A short history of
Describing APIs
OpenApi
RAML
GraphQL SDL
WSDL
gRPC
AsyncAPI
Postman collections
WADL
WIDL
Swagger
OData
OpenApi
Implementation First
Implement Server
Generate Docs
Implement Clients
Find problem
GOTO 1 or 3
design API
Design First
validate specification
implement server and client
GOTO 3 or 1
find problem
GOTO 1
Versioning
API
Client
Server
API-description language
Tools
Versioning
API
Client
Server
API-description language
Tools
Breaking Changes
as a path prefix /v1/
an API
Versioning
subdomain v1.my.service
in a version header
Roaster
OAD
PLAY
The Future
Hackability
Scaffolding
Design First APIs
By Juri Leino
