Building APIs that don’t suck!

(To be taken with a grain of salt)

Why?

Endpoint Theory

Noun vs Verb

POST /users

POST /users/create

Resources are NounsVerbs can be made NounsPOST /users/123/checkin

POST /users/123/checkins

Endpoint Theory contd...

Singular vs Plural

GET /users/1,GET /users

GET /user/1, GET /users

Use HTTP Verbs appropriately

GET Retrieve GET /users/123

POST Create POST /users

PUT Replace PUT /users/123

PATCH Update PATCH /users/123

DELET

E

Delete DELETE /users/123

Resource Relationships - keep it simple

GET /users/1/checkins

GET /users/1/checkins/123

GET /checkins/123

Use HTTP Status Codes appropriately

2xx Success 200(OK), 202(Created)

3xx Redirect 301(Redirect), 303(Moved

Permanently)

4xx Client Error 400(Bad Req), 401(Unauthorized),

404(Not Found),

422(Unprocessable)

5xx Server Error 500(Internal Err)

Payload Design - think of the user{

"data": {"type": "entity_type""attributes": {

....}

}}

{"errors": {

"status": 422,"title": "Bad api call","detail": "Details...”

}}

HATEOAS & being RESTful

1. Content Negotiation

Hypermedia As The Engine Of Application State

GET /configs

HTTP Header:

Accept: application/x-yaml

HATEOAS & being RESTful

2. Hypermedia Controls

"data": {"type": "users""attributes": {

....},"links": [ {

"rel": "self","uri": "/users/1"

}, {"rel": "checkins","uri": "/users/1/checkins"

}]}

FAQ

Versioning - Semantic Versioning (http://semver.org)

Documentation - Slate or Swagger

Testing - JSON-Schema validation

Standards - JSON-API, but I can’t recommend it!

UGLY Parts - Filtering, Foreign-Key relations, Sideloading

GraphQL - Not a REST API, Infinite API

Take Away

API

Be thoughtful when designing APIs

Follow good practices

Stay consistent

Try not to break it (Semantic versioning)

TLC

Thank you

“Life is short.. Work somewhere

awesome”

http://www.enova.com