restful api design and documentation - an introduction
TRANSCRIPT
miredotmiredotmiredot
Agenda
REST – What and Why?Basic REST Design PrinciplesDocumenting a REST APIQuick DemosMiredot
POST https://api.twitter.com/tweets { “status”: “Great to be at BeJUG" }
POST https://api.twitter.com/1.1/statuses/update.json?status=Great%20to%20be%at%BeJUG
*
*This is not the actual Twitter API **This is
**
miredotmiredotmiredot
REST – What and Why?
REpresentational State TransferThings/resources instead actions (SOAP/RPC)
Using HTTP the right way
Stateless (if possible)
Cache-able, Firewall-able, Proxy-able
(JSON) For purists: know the initial URI and navigate via hyperlinks (HATEAOS)
miredotmiredotmiredot
REST Design Principles
Religiously RESTful vs REST-like
Goals1. Easy to use API2. Predictable behavior3. Works with existing infrastructure (proxies, browsers)
Don’t think Java, think API first!
miredotmiredotmiredot
REST Design Principles – URI / Resource
https://api.acme.com/petstore/dogs/5/toys/2/parts
base URL
all the dogs
dog with id=5toy with id=2
all the toys of dog 5all the parts of toy 2
?material=plastic
Rule1: Plural for collections, ID for single elementRule2: No verbs! ../petstore/dogs/addRule3: Query params only for meta-info (filtering, format)
extra info
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
POST = Create
PUT = Update (or create)GET = Read
DELETE = Delete
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
201 CREATED “2”
{ “name”: “chicken” }
request response
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
200 OK { “name”: “duck” }
request response
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
200 OK { “name”: “Snoopy” “favouriteToy”: 2 }
N/A request response
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
200 OK [{ “name”: “Scooby Doo” }, { “name”: “Lassie” }]
N/A request response
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
200 NO CONTENT N/A request response
miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2
Rule1: GET is readonly, has no side effects (, cacheable)Rule2: POST creates, PUT creates or updates Rule3: GET/PUT/DELETE are idempotent
Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy
miredotmiredotmiredot
REST Design PrinciplesSee http://www.miredot.com/blog/posts/rest-api-design-basic-rules/
miredotmiredotmiredot
REST API Issues
GET has a side-effectNever do this as this is often cached, pre-fetched, etc.Will cause hard to debug problems
GET /accounts/3/balance à Wires €10 to Acme company
GET /accounts/3/balance
GET /accounts/3/balance
GET /accounts/3/balance
GET /accounts/3/balance
à Wires €10 to Acme company
à Wires €10 to Acme company
…
miredotmiredotmiredot
REST API Issues
Data in query parameters
POST https://api.twitter.com/statuses/update?status=Great%20to%20be%at%BeJUG
POST //api.twitter.com/statuses/ { “status”: “Great to be at BEJUG” }
PUT //api.twitter.com/statuses/4 { “status” : “Great to be at BEJUG” }
Client-generated ID
miredotmiredotmiredot
REST API Issues
Verbs in the resource path
Failed form of RPC
/getAccount /createDirectory
/group/update /dogs/4/bark
GET PUT POST ?
miredotmiredotmiredot
REST API Issues
How do I make a dog bark?
POST /dogs/5/bark
POST /dogs/5/commands/ { “command”: “bark” }
GET /dogs/5/commands/1 { “id”: 1, “command”: “bark”, “status”: “executed”, “time”: “2016-04-19” }
OptionalReify the action à commands
miredotmiredotmiredot
REST Design Principles – Other considerations
Payloads (prefer JSON)Big vs small, field naming: be consistent(HATEOAS)
Representation: one resource, multiple formatsAccept and content-type headers
VersioningHeader, accept/content-type, URL
SecurityOauth, don’t invent your own
miredotmiredotmiredot
Take care of your API
It’s the user interface of your service
Be API-centric, not Java-centric!
Design your API with the whole team
Review your API regularly
Be consistent above all
miredotmiredotmiredot
How Important is API Documentation?
For private APIs: VERYI DON’T want to look at your source code
For public APIs: Didn’t find a word to describeDevelopers will hate your API, you and your company.
miredotmiredotmiredot
Three Approaches
Write it yourselfWikis, Word, Web-pageDedicated Wikis
API Specification LanguageRAML, API Blueprint, Swagger
GenerateMiredot, Enunciate, Swagger, JsonDoc, APIDoc
miredotmiredotmiredot
Write yourself
1. Word: DON’T
2. Wiki: avoid
3. readme.io, gelato.io: Nice docs, flexibleREST/JSON-editorImport from Apiary, RAML, Swagger
Hard to maintainVery hard to test(Never in sync with the implementation)
miredotmiredotmiredot
API Specification Language
API First: focus on design
RAML, SwaggerSpec, API Blueprint (Apiary)
Cross-language, cross-framework
Hard to maintainTest your API through the spec: hard
miredotmiredotmiredot
RAML
Mulesoft, Anypoint platform
YAML based, very modular
Many tools, plugins: generate clients, documentation, parser, validator
Varying quality
API Specification Language
Swagger (2.0)
Smart Bear, Open API initiative
Both a spec and tooling, also YAML
Comes with core tooling (Swagger UI), several open source tools
SwaggerUI: runtime component, interactive documentation
More closely integration in your project (also Java)
miredotmiredotmiredot
Generators
Get documentation for free
Is my language / are my frameworks supported?Jax-rs, Spring-mvc / Jackson, Gson
Is the output correct?Does it understand all my Java code (types, generics, frameworks)?
Do I need to add anything to my code?
Documentation always in sync with implementationSit back and relax
miredotmiredotmiredot
Enunciate
One of the first generators for Java
Supported frameworksJax-rs
OutputsWebsite, client libraries, WSDL, WADL
Swagger
Supported frameworksJax-rs (very limited), Spring-mvc (via SpringFox)Requires its own annotations
OutputsWebsite, interactive api client, client libraries, server
stubs
miredotmiredotmiredot
Miredot
We were not satisfied with existing generatorsDon’t support all Java constructs (generics, inheritance, …) or frameworksHard to setup (hours/days)
Java SupportFull Jax-rs, Spring-mvc, Jackson, RestEasy, Guava, … Generics, inheritance, Optionals, Guava, …
OutputsWebsite (static), Word, RAML
Documentation quality reporting
miredotmiredotmiredot
Miredot
Free for open source, subscription for commercial projectsPay-per-endpoint
RoadmapDocumentation Quality Dashboard (Sonar-like)Version compatibility checking
miredotmiredotmiredot
Final Words
1. Carefully design your API, you’ll be stuck with it for a long time
2. Don’t let documentation be an afterthought: start from day one
3. Use the many tools that are out there, they help a lot!