Dos and Dont’s in REST
General principles for good URI design:
- Don’t use query parameters to alter state
- Don’t use mixed-case paths.Lowercase is best
- Don’t use implementation-specific extensions in your URIs (.php, .py, .pl, etc.)
- Do keep path segments short
- Do use query parameters for sub-selection of a resource; i.e. pagination, search queries
- Do move stuff out of the URI that should be in an HTTP header or a body
- Use plural names for all resources.
General principles for HTTP method choice:
- Don’t ever use GET to alter state; this is a great way to have the Googlebot ruin your day
- Don’t use PUT unless you are updating an entire resource
- Don’t use PUT unless you can also legitimately do a GET on the same URI
- Don’t use POST to retrieve information that is long-lived or that might be reasonable to cache
- Don’t perform an operation that is not idempotent with PUT
- Do use POST in preference to PUT when in doubt
- Do use POST whenever you have to do something that feels RPC-like
- Do use DELETE in preference to POST to remove resources
- Do use GET for things like calculations, unless your input is large, in which case use POST
General principles of web service design with HTTP:
- Don’t put metadata in the body of a response that should be in a header
- Don’t put metadata in a separate resource unless including it would create significant overhead
- Do use the appropriate status code
201 Created
after creating a resource; resource must exist at the time the response is sent202 Accepted
after performing an operation successfully or creating a resource asynchronously400 Bad Request
when someone does an operation on data that's clearly bogus; for your application this could be a validation error; generally reserve 500 for uncaught exceptions401 Unauthorized
when someone accesses your API either without supplying a necessaryAuthorization
header or when the credentials within theAuthorization
are invalid; don't use this response code if you aren't expecting credentials via anAuthorization
header.403 Forbidden
when someone accesses your API in a way that might be malicious or if they aren't authorized405 Method Not Allowed
when someone uses POST when they should have used PUT, etc413 Request Entity Too Large
when someone attempts to send you an unacceptably large file.- Do use caching headers whenever you can
ETag
headers are good when you can easily reduce a resource to a hash valueLast-Modified
should indicate to you that keeping around a timestamp of when resources are updated is a good ideaCache-Control
andExpires
should be given sensible values- Do everything you can to honor caching headers in a request (
If-None-Modified
,If-Modified-Since
)
Best practices
- Think nouns, not verbs while URI designing.
RESTful APIs are based on nouns — you’re performing actions on endpoints that are things. RPC/SOAP endpoints, on the other hand, are verbs — they’re things that are meant to do something.
2. Respect the change management process. Avoid introducing break changes to existing endpoints that people are using.
3. Be consistent. That means with HTTP status codes, general API structure, accepted best practices, etc.
4. Consider versioning from the start.
5. API documentation using tools like Swagger.
6. Handling errors in API requires careful planning.The REST API best practice here is to return error messages in the same format every time.
7. Always paginate your result
8. Separate your JSON responses into meta and data fields
9. Use query strings to manipulate data
Query strings should be used for sorting, searching, and filtering data. You can also pagination, as we talked about earlier, but query strings often make it easier to look through.