REST API Design In Practice


Bad Design

  • /users/addUser
  • /users/a1b2c3/verifyPassword
  • /roles/s8g3j8/updateRole
  • /tasks/submitTask

Resource Oriented

  • GET – read or find
  • POST – create
  • PUT – update
  • DELETE – delete

CRUD Operations

Header, URL and Form Handling

Form Handling

If it is a form post, you may want to get info like below:

Sometimes you may need to access the http request Header info OR to parse URL your own when the query parameters are very dynamic and you cannot simply create a method to capture it. Here is how:

Obtain the Header and cookie info

Obtain the URL

Error Handling

Separate client vs server error

  • 4xx Client error – codes are used to tell the client that a fault has taken place on THEIR side. They should not re-transmit the same request again, but fix the error first.
  • 5xx Server error – codes that tell the client the server failed to fulfill an apparently valid request. The client can continue and try again with the request without modification.

Provide as much info as possible for the client to fix the issue

HTTP status codes

HTTP defines a bunch of meaningful status codes that can be returned from your API. These can be leveraged to help the API consumers route their responses accordingly. I’ve curated a short list of the ones that you definitely should be using:

  • 200 OK – Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn’t result in a creation.
  • 201 Created – Response to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource
  • 204 No Content – Response to a successful request that won’t be returning a body (like a DELETE request)
  • 304 Not Modified – Used when HTTP caching headers are in play
  • 400 Bad Request – The request is malformed, such as if the body does not parse
  • 401 Unauthorized – When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
  • 403 Forbidden – When authentication succeeded but authenticated user doesn’t have access to the resource
  • 404 Not Found – When a non-existent resource is requested
  • 405 Method Not Allowed – When an HTTP method is being requested that isn’t allowed for the authenticated user
  • 409 Conflict (object already exist)
  • 410 Gone – Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
  • 415 Unsupported Media Type – If incorrect content type was provided as part of the request
  • 422 Unprocessable Entity – Used for validation errors
  • 429 Too Many Requests – When a request is rejected due to rate limiting

Can I throw appication Exception in the API?

The answer is yes. If you don’t want to capture all exceptions and create response, you can do the following:

Define the Global Exception class

Create exception mapper and register as provider thru annotation.

Then you can throw the BusinessException in your api and it will take care of the response creation for you.
See how we can throw the final BusinessException out and add in error messages to give user more info what is going wrong.



  • REST API Design By
  • Dropwizard + Spring

REST API Design In Practice

log in

Use demo/demo public access

reset password

Back to
log in
Choose A Format
Personality quiz
Trivia quiz