Dos and Dont’s in REST

General principles for good URI design:

Arun Rajeevan
N-OMS Tech Radar
Published in
3 min readMar 29, 2019

--

  • 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 sent
  • 202 Accepted after performing an operation successfully or creating a resource asynchronously
  • 400 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 exceptions
  • 401 Unauthorized when someone accesses your API either without supplying a necessary Authorization header or when the credentials within the Authorization are invalid; don't use this response code if you aren't expecting credentials via an Authorization header.
  • 403 Forbidden when someone accesses your API in a way that might be malicious or if they aren't authorized
  • 405 Method Not Allowed when someone uses POST when they should have used PUT, etc
  • 413 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 value
  • Last-Modified should indicate to you that keeping around a timestamp of when resources are updated is a good idea
  • Cache-Control and Expires should be given sensible values
  • Do everything you can to honor caching headers in a request (If-None-Modified, If-Modified-Since)

Best practices

  1. 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.

Sign up to discover human stories that deepen your understanding of the world.

Free

Distraction-free reading. No ads.

Organize your knowledge with lists and highlights.

Tell your story. Find your audience.

Membership

Read member-only stories

Support writers you read most

Earn money for your writing

Listen to audio narrations

Read offline with the Medium app

--

--

Published in N-OMS Tech Radar

This publication focuses on cloud technologies, application development, software architectures, best practices, the latest advancements in web technologies, and best engineering practices.

No responses yet