I believe the fastest way to explain what a good web RESTful service or API should look like or describe design principles is to follow a good example for a REST resource like Person:

  • List all persons. GET /persons
  • Bulk update persons. PUT /persons
  • Delete all persons. DELETE /persons
  • Find a person with a particular id. GET /persons/123
  • Get partial fields (this is very powerful and I strongly recommend to support it). GET /persons/123?fields=name,age
  • List a person’s friends (related or sub resources). GET/persons/123/friends
  • Find a person’s particular friend. GET/persons/123/friends/456
  • Create a person. POST /persons
  • Update a person. PUT /persons/123
  • Remove a person. DELETE /persons/123
  • Return a page of result (use offset and limit). GET /persons?offset=1&limit=25
  • General search (Google style). GET /search?q=Joe+Blog
  • For scoped search drop the search (again Google style). GET /persons?q=John+Dear
  • Field search – find all persons named John (this coud be replaced by a search all functionality, like in Google). GET /persons?q=(name,eq,John)
  • Avoid resource actions or verbs (Use travels sub-resource/connection for the person instead). POST /persons/123/action/travel?location=Euro
  • The default format is json and is not required in the URL or Accept header, but the server needs to support it. GET /persons
  • Specify the format in the URL as .json if we need to support multiple formats. Accept: application/json or GET /persons/123.json
  • Return HTTP status codes with detailed message useful to people in the body (payload) – the minimum codes that every service should support are:
    • 200 (OK),
    • 201 (Created),
    • 400 (Bad Request),
    • 500 (Internal Server Error),
    • 404 (Not Found),
    • 401 (Unauthorized),
    • 403 (Forbidden)
  • Keep your APIs backwards compatible, but if you really have to version use full v# numbers in your URI (some people disagree and want the version in the HTTP headers, as it should be handled just like format since it is for the same resource). /v1/persons
  • Simple rule: if it changes the logic to handle the response it should be in the URL (easy to see), while if it doesn’t (like Auth information) or you want it secure it should be in the headers
  • JSON formatting rules: camelCase for all field names, ISO 8601 for dates
  • Last thing: your API should be easy to understand and try out in 5 min or less

As an inspiration I used the following resources:


Leave a Reply