Dos and Dont’s in REST
- 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 Createdafter creating a resource; resource must exist at the time the response is sent
202 Acceptedafter performing an operation successfully or creating a resource asynchronously
400 Bad Requestwhen someone does an operation on data that's clearly bogus; for your application this could be a validation error; generally reserve 500 for uncaught exceptions
401 Unauthorizedwhen someone accesses your API either without supplying a necessary
Authorizationheader or when the credentials within the
Authorizationare invalid; don't use this response code if you aren't expecting credentials via an
403 Forbiddenwhen someone accesses your API in a way that might be malicious or if they aren't authorized
405 Method Not Allowedwhen someone uses POST when they should have used PUT, etc
413 Request Entity Too Largewhen someone attempts to send you an unacceptably large file.
- Do use caching headers whenever you can
ETagheaders are good when you can easily reduce a resource to a hash value
Last-Modifiedshould indicate to you that keeping around a timestamp of when resources are updated is a good idea
Expiresshould be given sensible values
- Do everything you can to honor caching headers in a request (
- 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.