RESTful Web Services are basically REST Architecture based Web Services. In REST Architecture everything is a resource. RESTful web services are light weight, highly scalable and maintainable and are very commonly used to create APIs.

Why has REST API become so popular ?

• Separation between the client and the server.
• Visibility, reliability and scalability.
• The REST API is always independent of the type of platform or languages.

Today there are no projects or applications that don’t have a REST API for the creation of professional services based on this software. Without them any horizontal growth would be practically impossible. This is because REST is the most logical, efficient and widespread standard in the creation of APIs for Internet services.

Here is defining all the important guidelines which should be implemented to make Web APIs:

• Highly secure and efficient.
• Friendly to the developer and be explorable via a browser address bar.
• Simple, intuitive and consistent to make adoption not only easy but pleasant.
• Efficient, while maintaining balance with the other requirements.

1. Request Format

Request should be same through out the APIs. It should be flexible and easily understandable. It should contain two parts:

• Request Headers
• Request Data

1.1. Request Headers:

Following are the request headers which must be included in request:

• DeviceInfo – This header helping in fetching device information on which client application is running.  For ex – Device Manufacturer, model, OS version etc.
• AppInfo – This header is used to fetch client application version information.
• UserInfo – Id of user using the client application.
• Authentication – Parameter used for application authentication.
• UserAuthentication – Parameter used for user authentication.
• ClientType – Type of client like iOS/Android/Web.

1.2. Request Data:

Request data will contain actual data for the API. Request data should be in kay value pair.

2. Response Format

Response format should contain two parts:

• responseStatus
• responseData

2.1 Response Status

Response status should contain a status code for response other than http status code so that client can handle response on the basis of response code.

2.1.1 Success (Positive) Response 

In this case “responseStatus” will contain one field that is ”statusCode”. This field will be zero in case of success.  Http status code: “200 OK”.

2.1.2 Negative Response

There are different ​scenario​s in which negative response is given to the user. We need to send different HTTP status codes for different scenarios. Negative response should be specific and should contain a user friendly message. For example:

2.2 Response Data

Response data should contain actual data returned by the API.

3.Application Security

Application Security can be achieved through –

3.1 App Authentication

App authentication can be done using the information coming in headers. Authentication should be done in filter before actual api read request so that invalid request can be identified before actual processing.

3.2 User Authentication  

User authentication can be done using the information coming in headers. Authentication should be done in filter before actual api read request so that invalid user can be identified before actual processing.

4. Client Version Support

Over a period of time API will change and transform to higher versions. It would be difficult to support old version of client communicating with the latest version of API and we would like  old version client to upgrade to the latest version. API in such case must send response that client can understand and can provide a message to user to upgrade client.

5. Exception logging

Every exception which came on the back-end server should be logged into the database. Exception should be logged through asynchronous job so that other processing can be work without any conflict.

6. Request response logging

Every request/response came on the back-end server should be logged into the database. This should be done in an asynchronous task or job.

7. File logging

All the minor communications and events happening within the application should be logged in a log file. “Log4j” can be used for it.

8. Use nouns

Noun should be used for api resource instead of verb. Do not mix up singular and plural nouns. Keep it simple and use only plural nouns for all resources. For example:  /cars instead of /getAllCars

9. Use HTTP Methods to Operate on your Resources

Use URLs to specify the resources you want to work with. Use the HTTP methods to specify what to do with this resource. The four HTTP methods GET, POST, PUT, DELETE should be used for CRUD functionality (Create, Read, Update, Delete).

• Read: Get should be used for reading resources. GET requests never ever change the state of the resource.
• Create: POST should be used for creating new resources.
• Update: PUT should be used for updating existing resources.
• Delete: DELETE should be used for deleting existing resources.

10. Camel Case for Attribute Names

Attribute name in request/response should be in camel case. Like: