REST based APIs are increasingly becoming popular among developers today. Thanks mainly due to apps market REST based APIs becoming a de facto standard. Some main points in favor of REST API are:
It is open standard.
Based on standard HTTP protocol.
Support for various type of data format (like normal form parameters, XML, JSON etc) .
Light weight as compared to other standards such as SOAP
REST standards don’t specify much rules/restrictions on APIs . Due to this its very easy to do a bad design which might lead to lots of confusion and redundancies while developing APIs as well as creating APPs for consuming them . Sometimes it might even lead to performance and security related issues as well . So its very important to take proper care of certain good practices while designing REST based services .
Here are some guidelines:
1) Proper Naming and Versioning:
This is the base of API design. Its highly recommended to use your api name, version and entity/operation name in your API signature. Also, as a good design practice, you should use nouns in api URL and never use verbs. For example, http://api.mydomain.com/users is a proper way instead of something like http://api.mydomain.com/getusers . In case of versioning, you can use something like http://api.mydomain.com/myservice/v1/account or else http://api.mydomain.com/myservice?version=v1 .
2) Use of HTTP Methods:
REST is basically a way of developing web services using all the properties of standard HTTP protocol. HTTP methods play a significant part in determining operation which API represents. For the sake of simplicity and consistency its better to use URL like /users and POST method instead of something like /user/create for an API signature which creates a user in system.
3) Proper Use of HTTP Headers:
In case you are supporting multiple formats ( like XML/JSON) in your input or output in that case you can utilize Content-Type or Accept headers to denote that. For example, if you have an API which can accept both XML and JSON payloads then you can simply write in your API specification as Content-Type: “application/json” Content-Type: “application/xml” as supported values and have the same request URL for your API. It would be lot better than having something like /user?format=xml or /user?format=json in request specifications. Similarly, in case your API supports response caching on server side then you can use ETag header for that.
4) Proper Use of HTTP status codes:
There are some well defined status codes in HTTP protocol which serve specific purpose. Proper use of these status codes is sometimes neglected while API design but if used effectively this can solve lots of redundancy while providing API responses it can simplify API design to a great extent. It is recommended to use status code 201 in response of a create operation, 401 in case of wrong credentials in input, 403 in case of unauthorized access to a resource and so on. For example consider a scenario when you have to update a user data whose Id doesn’t exist anymore. In such case you should give 404 status code which means the resource is not found instead of 400 (bad request) error code with some error response message. Similarly if someone is using wrong Http Method (say GET in place of POST) then you should return standard HTTP status code 405 (which stands for method not allowed) in response.
5) OPTIONS call:
In HTTP protocol there is a provision for OPTIONS method which returns which all methods are supported to access this API resources. It’s a nice to have feature if you support OPTIONS call for each API you are designing so that the consumer developers can make OPTIONS call whenever necessary to get list of all supported HTTP methods of your API.