API Architecture — Design Best Practices for REST APIs

REST APIs everywhere!

Source: memegenerator.net

Just so we’re clear…

Source: giphy

1. Learn the basics of HTTP

Source: imgflip.com

2. Do not return plain text

Source: meme-arsenal

3. Do not use verbs in URIs

Source: quickmeme
GET: /books/:slug/generateBookCover/
GET: /books/:slug/bookCover/
# Don’t do this
POST: /books/createNewBook/
# Do this
POST: /books/

4. Use plural nouns for resources

Source: gifer.com
GET: /books/2/
POST: /books/
...

5. Return the error details in the response body

Source: Gif Abyss
{
"error": "Invalid payload.",
"detail": {
"name": "This field is required."
}
}

6. Pay special attention to HTTP status codes

Source: Giphy
{
"status": "success",
"data": {}
}
HTTP/1.1 200 OK
Content-Type: text/html
{
"status": "failure",
"data": {
"error": "Expected at least three items in the list."
}
}
Source: tenor
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Expected at least three items in the list."
}

7. You should use HTTP status codes consistently

Source: Tenor
GET: 200 OK
PUT: 200 OK
POST: 201 Created
PATCH: 200 OK
DELETE: 204 No Content

8. Do not nest resources

Source: memes.com
GET: /authors/Cagan/books/
GET: /books?author=Cagan

9. Handle trailing slashes gracefully

Source: tenor
POST: /buckets
POST: /buckets/

10. Make use of the querystring for filtering and pagination

Source: tenor
GET: /books?page=1&page_size=10
GET: /books/published/
GET: /books?published=true&page=2&page_size=10

11. Know the difference between 401 Unauthorized and 403 Forbidden

Source: http.cat

12. Make good use of HTTP 202 Accepted

13. Use a web framework specialized in REST APIs

Source: memegenerator.net

Closing thoughts

Source: memegenrator.net

Technologist skilled in building web experiences customers love. Today I secure big data in the cloud. Holistic problem solver. All views shared are my own.