One of the most common questions we get asked by people who are new to the world of REST-APIs is how to develop some really good ones. However, in reality, what they want to be asking is how web API design works using the REST pattern. While there is a pretty elaborate explanation below, let’s start with the oversimplified version. As long as you understand all the underlying principles of initiating the HTTP protocol, all that’s needed is some good data modeling to structure the API on that foundation. Below we go a little more into detail about designing an API.
Understanding REST and the HTTP Foundation
Now let’s just clarify that designing a REST-API is something that’s best geared towards people who have data modeling skills. REST is primarily based on using a couple of resources which need to follow a specific type of data model.
All communication on the internet is via HTTP. Take,for instance, a browser which sends a series of HTTP requests to a web server which then in return sends a response back. HTTP along with HTTPS which is the secure version of the protocol are the predominant client-server communication protocols used. Using the protocol allows clients to not only query but at the same time send requests to manipulate server-based information or resources such as:
- Returning of a web page via the URL
- Delete specific resources through that URL
- Creating resources as well as listing all available resources
The resources we listed above can be anything ranging from content on a webpage to objects like sensors, motors, encrypted data,etc. However, the one thing you need to keep in mind about the HTTP protocol is that everything has an address and with that address, there are a set of commands usually in the form of ‘verbs’ like create, delete, update, refresh,etc. It is these set of verbs which are called RESTful where the ‘R’ actually means resource.
Everything connected to the internet can be a server in some conversation,or it is a client. It is for this reason that people consider the internet as having a peer to peer protocol structure. The REST API tends to be native to the interface of the network, and the best way to expose functionality via the internet.
Designing a REST-API
Any enterprise that hopes to become genuinely digital or connected will need to have valid HTTP servers. The REST-API happens to be the primary channel through with all the information will travel. Thankfully, designing a good RESTful API is comparatively easy if you just follow the steps below.
- The REST-API should expose the server’s resources which are then able to be manipulated via the clients API. The data model will work as a sort of metaphor through with the clients can easily connect to the API. The API will also have both physical and logical resources along with their associations.
- Steps should be taken to ensure that the resources are exposed which is done by URL mapping. The URL needs to reflect all the relationships with other resources.
- Manipulations then need to be assigned to every HTTP command like POST, DELETE, PUT, GET,etc.
- Valid request formats should be created for the required entries into the model.
- URLs need to be protected by authorization procedures and validations.
What’s Next with REST-APIs
Designing a REST Web API is a process that requires an understanding of how the internet works. It should also be clear as to what objectives need to be achieved. Once that’s done the above-mentioned list will help to work as a checklist when designing the API.
