REST API Best Practices: a REST Cheat Sheet

I'm interested in REST API design and identifying the best practices for it. Surprisingly, a lot of APIs that claim to be RESTful, aren't. And the others all do things differently. This is a popular area, though, and some best practices are starting to emerge.  If you're interested in REST, I'd like to hear your thoughts about best practices.

REST is not simply JSON over HTTP,  but most RESTful APIs are based on HTTP. Request methods like POST, GET, PUT and DELETE are used to implement Create, Read, Update and Delete (CRUD) operations. The first question is how to map HTTP methods to CRUD operations.

To start, here's a "REST API Design Cheat Sheet" that I typed up and pinned to my wall. Its based on the book "REST API Design Rulebook", and the HTTP RFC. I think it reflects standard practice. There are newer and better books on the subject now, but this list covers the basics of HTTP requests and response codes used in REST APIs.

Request Methods

• GET and POST should not be used in place of other request methods
• GET is used to retrieve a representation of a resource
• HEAD is used to retrieve response headers
• PUT is used to insert or update a stored resource
• POST is used to create a new resource in a collection
• DELETE is used to remove a resource

Response Status Codes

• 200 "OK" indicates general success
• 200 "OK" shouldn't be used to return error messages
• 201 "Created" indicates a resource was successfully created
• 202 "Accepted" indicates that an asynch operation was started
• 204 "No Content" indicates success but with an intentionally empty response body
• 301 "Moved Permanently" is used for relocated resources
• 303 "See Other" tells the client to query a different URI
• 304 "Not Modified" is used to save bandwidth
• 307 "Temporary Redirect" means resubmit the query to a different URI
• 400 "Bad Request" indicates a general failure
• 401 "Unauthorized" indicates bad credentials
• 403 "Forbidden" denies access regardless of authentication
• 404 "Not Found" means the URI doesn't map to a resource
• 405 "Method Not Allowed" means the HTTP method isn't supported
• 406 "Not Acceptable" indicates the requested format isn't available
• 409 "Conflict" indicates a problem with the state of the resource
• 412 "Precondition Failed" is used for conditional operations
• 415 "Unsupported Media Type" means the type of payload can't be processed
• 500 "Internal Server Error" indicates an API malfunction

A note about the PATCH method. There are good reasons to consider using the HTTP PATCH method for partial updates of resources, but because it's not supported everywhere, and because there are workarounds, I haven't added it to my cheat sheet yet.

Other Posts in this series

REST API Best Practices 2: HTTP and CRUD
REST API Best Practices 3: Partial Updates - PATCH vs. PUT
REST API Best Practices 4: Collections, Resources and Identifiers