@simonrenoult | srenoult@octo.com
Simon Renoult
RESTful API Design.
Pragmatic
should be
Accessing data
SIMPLE
REST API.
What?
[{
"id":"007",
"first_name": "John",
"last_name": "Lennon",
"age": 76,
"gender": "M",
"albums": "/v1/people/007/albums"
}]
Pragmatic.
Why?
Used by developers
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.
HTTP status codes.
HTTP for the rescue.
Success.
200
201
204
206
OK
Created
No content
Partial content
GET /people
POST /people
DELETE /people
GET /people
Client.
400
401
403
404
Bad request
Unauthorized
Forbidden
Not Found
Server.
500
503
Internal Server Error
Service Unavailable
Do NOT stick to the spec at any price.
Be affordable first.
Documentation first.
An API is only as good as its documentation.
Curl
Swagger
Always provide curl samples
Open API Spec. (fev 2016)
Use HTTP.
Be simple.
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
Pragmatic RESTful API Design
By Simon Renoult
Pragmatic RESTful API Design
Set of good practices (seen on the ground) to design a good RESTful API.
