6. 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
7. Resource Relationships - keep it simple
GET /users/1/checkins
GET /users/1/checkins/123
GET /checkins/123
8. 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)
9. Payload Design - think of the user
{
"data": {
"type": "entity_type"
"attributes": {
....
}
}
}
{
"errors": {
"status": 422,
"title": "Bad api call",
"detail": "Details...”
}
}
10. HATEOAS & being RESTful
1. Content Negotiation
Hypermedia As The Engine Of Application State
GET /configs
HTTP Header:
Accept: application/x-yaml
I wanted to get myself to read the book. So I signed up for an Enova tech tech talk, where I work.
Prefer nouns to verbs to represent endpoints. Why? Because URLs represent a Resource which lives on the Internet. It’s a thing (noun)
You can still make a verb into a noun if needed. Eg. checkin is an action but checkins a list of checkins. Like a verb but Likes a noun.
Use Plural. Don’t use both. It’s more consistent and less ambiguous
Verbs exist in the REST world. But use the HTTP built-ins to achieve it.
Best not to go more than 1 level deep. If you need to do the 2nd example, do the last one instead
Use HTTP status to convey how things went. Make a best effort to use the correct http status code (even though there are overlapping codes)
Highly subjective, but try to come up with a payload design and try to be consistent. This design is inspired by json-api. Why not json-api? It can get too complex and ugly
It ain’t RESTful if it doesn’t have HATEOAS. That’s what Roy Fielding, the inventor or REST says. Content negotiation not a big deal these days since it’s pretty much json.
However supporting hypermedia links is important. It promotes organic API discoverability.
Times almost up. The one I spent some time talking about is API testing via json-schema. I think it can be used to address most of API testing. If you want to be exact then use more exact matching of data against a golden file but IMHO that isn’t really needed here.
Good API design is important. It imputes thoughtfulness into a well designed system (even if that is not the case :). Don’t think of APIs as web page replacements. Instead think of them as schemas and data. Thinking of good API designs may invite to re-evaluate current design decisions and set you on a path to simplicity nirvana.