@simonrenoult | srenoult@octo.com
Simon Renoult
RESTful API Design.
A.K.A.
RESTful API in 15mn
API.
Whaaaat?
GET /people?first_name=John
> 200 OK
[{
"id":"007",
"first_name": "John",
"last_name": "Lennon",
"age": 76,
"gender": "M",
"albums": "/v1/people/007/albums"
}]API.
Why?
System interoperability
External innovation
Business opportunities
API.
RESTful?
Developer oriented
Easy to reuse
URLs.
It's all about affordance.
Use HTTP verbs.
GET
POST
PUT
DELETE
PATCH
Read something. No side-effect.
Create something.
Update or create something.
Remove something.
Update (partially) something.
Give me a name.
Verbs?
And a good one.
No, HTTP takes care of that
Resource
We manipulate (HTTP verb) a resource (noun)
Consistent case.
CamelCase
Snake_case
Spinal-case
GET /v1/orders?userId=007
GET /v1/orders?user_id=007
GET /v1/orders?user-id=007
Just... Be consistent.
You are not alone.
Root object is a collection.
/client
Nop.
/clients
Yes!
Version everything.
Things will change.
In the headers
As a query parameter
In the URL path
Nop!
Meh...
Yes!
HTTP status codes.
HTTP for the rescue.
Success.
200
201
204
206
OK
Created
No content
Partial content
GET /pokemons
POST /pokemons
DELETE /pokemons
GET /pokemons
Client.
400
401
403
404
Bad request
Unauthorized
Forbidden
Not Found
Server.
500
503
Internal Server Error
Service Unavailable
Query strings.
Don't be smart. Be standard.
Search.
GET /v1/products/search?name=la*Pagination.
GET /v1/products?range=0-24Sort.
GET /v1/products?sort=foo&desc=barPartial response.
GET /clients/007?fields=name,address(street)
Other key concepts.
A.K.A. "Fourre-tout"
Non-resource scenarios.
When real life hurts.
POST
Verbs
Manipulate actions instead of resources
Stay RESTful-ish. POST is :
- not safe
- not idempotent
Search cross-resource
Activate or deactivate something
Send a password recovery email
POST /v1/search
Make it RESTful. You can do it.
POST /v1/recovery-email
Don't be RESTful at any price.
Be affordable first.
HATEOAS.
HAL
Hydra
JSON-LD
RFC5988
New kid in the block
Define a set of "standard" link
Cool kid in the block
Yet another kid in the block
That's just links.
Up to you guys...
Architecture.
Because it matters. A lot.
KISS.
Don't use business specific terms
One way to do things
Design for your clients, not your data
Design for the many, allow the few (80-20)
Granularity.
Not too big. Not too thin.
One URL, one resource
GET /clients/007
{
"id":"007",
"name":"Bond",
"address":"/v1/addresses/362"
}
GET /addresses/362
{
"id":"123",
"street":"Avenue des Champs-Elysées",
"country": "/v1/countries/839"
}
One URL, one content
GET /clients/007
{
"id":"007",
"name":"Bond",
"address": {
"street-number":"50",
"street":"Avenue des Champs-Elysées,
"country:"france"
},
"articles": [{
"id":"ab3423fds",
"name":"foo",
"description":"foo bar"
}],
"comments":[{
...
}],
"private-messages":[{
...
}]
}
Security.
HTTPS everything
OAuth2/OIDC no matter what
API domain names.
https://api.fakecompany.com
https://api.sandbox.fakecompany.com
https://developers.fakecompany.com
https://oauth2.fakecompany.com
https://oauth2.sandbox.fakecompany.com
Documentation first.
An API is only as good as its documentation.
Curl
Swagger
Always provide curl samples
Open API Spec. (fev 2016)
Conclusion
Use HTTP.
Be affordant.
Ship it.
Questions?
Thanks.
Useful resources
http://vinaysahni.com/best-practices-for-a-pragmatic-restful-api
https://httpstatuses.com/
Design
Tools
http://blog.octo.com/designer-une-api-rest
RESTful API Design
By Simon Renoult
RESTful API Design
Set of good practices (seen on the ground) to design a good RESTful API.
