RESTFul Webapi Implementation Guidelines

REST-WebApi Implementation Guidelines



As we are going into the era where all devices needs to be connected with the server there is a need to build an API that is easy to use and all devices speaks the same langugage.

What is REST?

Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol — and in virtually all cases, the HTTP protocol is used.

What is Hypermedia?

In layman term, when the REST response comes back then it should include some webapi resources as a reference for the client. This way the client can get to know some valid URI that can be called by the client.

  • Method of self-describing messages
  • Hypermedia as The Engine of Application State == HATEOAS
  • Hypermedia can create dynamic, self-documenting APIs
  • But you can be a great API without HATEOAS


Web Services Vs REST

The concept of API is in development industry since COM, however, what has been changed now is how easy this API is available for different devices.

COM       Limitation: COM should be packaged along with the program. COM is accessible for only specific programming langugage, which means C++ dll is not directly accessible to Java.
 DCOM   Limitation: A proxy needs to be installed on local machine. Again a compatiblity issue, permission headache.
ASMX    Web service that is accessible through HTTP protocal and the client only needs to know how to call through a proxy that uses SOAP as a message protocol.
SVC Client still needs to have a knowledge to interpret SOAP.

Why Web service era is drying… Web service calls require a standard to be followed such as SOAP. Not all devices knows about these standards. This adds a complexity to provide a library at client level that can communicate in SOAP message format and web service can be connected. In case of REST WebApi it uses http. Thus, it has less overhead as compare to previous technology. Now what it means to your coding that your functions are available as is from Mobile to a Desktop. All you need is HTTP to call, which is available even in 20 $ mobile phones.

Should you use REST?
  • REST or REST-ful APIs are easy to consume and maintain
  • If your API does not fit the Resource Model, RPC or custom APIs are fine
  • Your new development should starts from REST principle and if does not fit then please proceed with the old procedure.

What will you learn here?

Idea behind this article  is to give you guidelines on what should be done for making a a good Web API. This document is listing some points that I have learnt and implemented (some :-)) for WebApi architecture. You can implement these rule in any programming language. Let us understand these rules.


1. » Don’t use verb as a part of the URL. So rather than saying that /todos/update it should be URL: /todos METHOD: POST or PUT.

The main reason of not using verb is because as the project extend there are too many URI and it is hard to main these URI. Thus, it makes it difficult to manage your API.

1.1» Use Identifiers to locate individual items in URIs. It does not have to be internal key.

e.g. (internal key)
or (non internal key - however unique identifier to determine that single entity)

1.2» Use either Plural or Singular noun. However, don’t mix it.

Preferred Preferred Not Preferred
/polls/23 /poll/23 /polls/23
 /todos/2384  /todo/2384  /todo/2384

2. » Concrete is Good over Abstract; so instead of saying /items/23 it should says the type of items like /cars/23

3.» Don’t use query string (?) in the URL, where possible; Set Association resources/id/resources through url.


4.» Use pre defined HTTP status code in your returned header of Api methods. refer available HTTP code at

5.» You should also give an option to supress the code by giving an optional parameter which will force API to always return 200. suppress_response_codes. /customers/1? suppress_response_codes=true 

Response should be:

HTTP status code: 200 {"error":"Could not authenticate you."}

6.»  Make the version mandatory. Specify the version with a ‘v’ prefix. But keep in mind that API version is not product version. There are 4 types to implement Versioning:

  • Version as a part of URL – The main drawback is maintaining client on url change.If you are defining URL based version then move it all the way to the left in the URL so that it has the highest scope (e.g. /v1/customers).
  • Version as a part of Querystring – Same drawback as above.
  • Version as Content Type in Accept Header – The main drawback of this approach is it adds complexity implementing custom header on all platform. It can also encourage increased versioning which cause more code churning.e.g. Accept : vnd.api.v1.customer
  • Version as Custom Header – Same drawback as Content Type.e.g. x-api-version: 2 or  x-api-version: 10-07-2014

Whichever way you go, use a simple ordinal number; Don’t use the dot notation like v1.2; Before obsoleting previous versions give developers at least one cycle to react.

7.» Implement partial response; Partial response allows you to give developers just the information they need.

  • Implement Partial GET
  • Implement Partial Patch

8. » Make it easy for developers to paginate objects in a database; Use limit and offset to make it easy for developers to paginate objects.

9.» Accept different format and content negotiation is a Best practice. Use Accept header to determine which formats are allowed.

GET api/customers/1 HTTP/1.1
Accept: application/json, text/xml
Host: localhost...

10. »  Use JSON as a default return type, following Javascript camelCasing conventions for naming attributes.

e.g. {"firstName":"Joe","lastName":"Public"}

11.» Standard place to host is and if the request is coming from the browser, then redirect it to Also, redirect any request coming for dev, developer to

12.» On successful update, return 200 (or 204 if not returning any content in the body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation.

13.» It is strongly recommended to use POST for non-idempotent requests. POST is neither safe or idempotent. It is therefore recommended for non-idempotent resource requests.

14.» PUT vs POST for Creation In short, favor using POST for resource creation. Otherwise, use PUT when the client is in charge of deciding which URI (via it’s resource name or ID) the new resource will have: if the client knows what the resulting URI (or resource ID) will be, use PUT at that URI. Otherwise, use POST when the server or service is in charge of deciding the URI for the newly-created resource. In other words, when the client doesn’t (or shouldn’t) know what the resulting URI will be before creation, use POST to create the new resource.

15.» Choose CORS whenever and wherever possible.

16.» Non-Resource API

  • Be sure that the user can tell it is a different type of operation
  • Be pragmatic and make sure that these parts of your API are documented
  • Don’t use them as an execute to build a RPC API

17.» It is recommended to return an Entity Tag (ETag) header for each GET (read) operation. It should support Week Tag, starts with W/ and supports Strong Tag. if-None-Match header key is used for specifying the ETag value.

GET: /api/customers/1 HTTP /1.1
Accept: application/json, text/xml
Host: localhost
If-None-Match: 823748374783

Request response should return 304 status code.

18.» Protect your Api

  • SSL is almost always appropriate.
  • Secure the API itself using:
    • Cross Origin Security:
    1. JSON with Padding (JSON)  – not recommended coz the callback has to be maintained.
    2. Cross Domain Resource Sharing (CORS) –

19.» Authorization & Authentication 1. Authorization – Use API Keys 2. Authentication  – Options:

    • Website security such as Form, Windows Auth, 1st Party Developer (internal auth.)
    • Use OAuth 3rd party Developer (external auth.)

In the next series of post, I will explain & implement these rules with the help of .NET WEB API programming language.    stay tuned…. Connect with me: View Amit Malhotra's profile on LinkedIn.

Tips #1 camelCase Json from webApi


I have came into the situation where I need to build webapi that returns value in camel case so that it is defined as per javascript writing notation standard.



I have two options that either I define json property for each POCO ( Plain old CLR object).

 public class TodoItem

public int ID { get; set; }
 public string Title { get; set; }

 public bool Completed { get; set; }

This way Json seialization woudl know how it should represent the json result.

The another solution by using Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver class.

Use this below snippet to configure the serialization format.

config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

I have wrote this line at WebApiConfig.cs file for WEB API project:

public static void Register(HttpConfiguration config)
// configure serialize settings so that the response comes as camel case serialization.
 config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();