Representational State Transfer (REST) is an architectural style that is used in developing web-based services. By insisting on a number of constraints regarding how services constructed on the principles of REST communicate and interact with each other, it offers a way to simplify the implementation of interoperability.
REST APIs are built using the Hypertext Transfer Protocol (HTTP) as its underlying method of communication. This eliminates the need to use more complex protocols such as COBRA and RCP and reduces overhead in the development process. It brings with it a familiarity to anyone who is experienced in web development and interacting with the Internet.
Other tenets of REST include the separation of clients and servers, by enforcing a uniform interface. This allows the servers and clients to go their own way as far as development and evolution of their functionality while retaining the ability to exchange data through the uniform interface. Any language that can send a request via HTTP can be used to develop a REST API.
There are many examples of REST APIs in use today. You probably interact with some of them on a regular basis. According to openclassrooms.com, some of the more familiar REST APIs that you encounter as you move around on the Web are Instagram, Gmail, Github, and Weather Underground.
Here are some tips to keep in mind if you are delving into the world of REST APIs.
1. Identifying the Object Model
According to restfulapi.net, this is the first step you should take when designing a REST API. This entails determining the objects that will be presented as resources in your Web service. Depending on what your service intends to do, these resources will vary. They can be users, documents, devices, or just about anything else that can be represented as hypermedia. Everything else you do with your API is going to be determined by what resources you will be working with, so this is a logical and great place to start.
2. Understanding How Requests for Information Are Made
REST requires clients to make requests to servers if they want to access or modify information. The form of the request consists of an HTTP verb (more on those below), a header, a path to a resource, and an optional message body that may contain data. The HTTP verb defines the type of operation that is being requested of the server and the header supplies information pertaining to the request. The path is to a resource or location where the operation is to be performed.
3.Understanding HTTP
Since this protocol is used extensively in developing REST APIs, it is in your best interest to understand what can be done within its parameters. Requests to interact with resources in a REST implementation use one of these five HTTP verbs to convey the operation to be performed:
Get – retrieve a resource or collection of resources by id
Post – create a new resource
Put – update a resource that has been specified by its id
Delete – remove a resource identified by its id
Patch – partially update a resource by id
4. Return proper HTTP status codes
Though the temptation may exist to simply return a 200 status code, using the correct codes will make your API more useful in the long run and better able to interact with other applications. Codes to use include:
200 – Success, all is well.
201 – Use for a POST request and a successful creation of a new resource
204 – Successful deletion of a resource
400 - denotes an invalid request with insufficient parameters
401 – Unauthorized access attempted
403 – Forbidden due to permissions
404 – Resource not found
500 – Internal server error. Accompany this with a human-readable message for your user.
5. Use nouns for resource names
The use of nouns as resource names, and in particular plural nouns, will make your job of maintaining your API much simpler. Your resources will be URLs. An example is when developing an API for managing employees. A simple implementation would allow us to add, delete, list and modify employee information.
By naming your resources with plural nouns, such as /employees, you can let the HTTP verb control the action that you want to be performed on your resource. Using an id, like /employees/1, you could get information about the employee with an id of 1. It is much simpler and cleaner to then do things like Put /employee/1 or Get /employee/1 as opposed to using constructs such as /addEmployee or /deleteEmployee.
6. Versioning your API
This may not be an issue with an in-house API, but if you expect any outside users to use it then versioning can be a critical if often overlooked precaution to take with your development. As your API evolves and you add new functionality or features, you should always strive for backward compatibility. This is not always possible, and you need to alert your customers to the fact that the API has changed, it can impact them and their business.
A good practice is to include the version number in the URL of your API so no misunderstanding can occur. Making changes without proper notice can lead to irate customers and even potential legal action.
7. Use request and response headers
The use of headers allows you to convey more information about the resource you are working with at the time. HTTP provides some standard request headers such as:
Accept
Content-Type
If-Match
If-None_match
HTTP also has some standard response headers like:
Allow
Content-Type
Tag
Status
The use of these headers lets your requests and responses convey additional information that can help to optimize your API. For instance, you can specify what types of responses are valid in the request ‘Accept’ header. The ‘Allow’ response header lets you stipulate which request types can be made for this object or entity.
Conclusion
Creating a REST API is a complex undertaking, but with best practices, can be a less forbidding task. These are some of the ways that you can give yourself a better chance of developing a useful REST API.