Web API design has one of the most important topics over the past years. As professionals in the development industry we work with dozens of backend solutions each year and so nothing matters more to us than straightforward API design. Completing the Microsoft Web API certification may help you hone your skills relating to this important part of your work. Generally, our recommendation is to use the RESTFul design for all web APIs. REST is used because it separates the API into numerous logical resources they use the Delete, GET, Put, HTTP and Post methods. Below we share a couple of ideas for clean RESTful API design.
Try Using Nouns and Avoiding Verbs
Why is this important? Well because it makes structuring the API easy. Usually, Verbs are reserved for actions that manipulate resources on the server. Though there is no law against using Verbs but ‘Read’ is perhaps more appropriate than ‘Get’ when trying to access a document for instance.
HTTP Headers for All Serialization
Another thing you’ll want to do is stick with using HTTP headers for all serialization formats. The client and the server have to know which format is being used for communications. That format needs to be addressed in the header. The Content-Type will address the request format while ‘Accept’ will define a list of all the most acceptable formats for a response.
Use Paging Effectively
It is important to use limit and offset because it is commonly used in all leading databases and is flexible for users. The default is limited to 20 while offset to ‘0’. You can use code like HTTP header: X-Total-Count to list entries to the user.
Linking to next and the previous page needs to be addressed in the HTTP header too. This is important to follow the link header values and not just build your URLs.
Enable HTTP Method Override
Now there are some proxies that will only support GET and POST methods. If you want to use a RESTful API within these limitations, the API needs a way to override this HTTP method. One way to do this is to use the custom designed HTTP Header X-HTTP to override its POST Method.
Snapshotting Dashboard Data
One of the drawbacks of using any subresources is that when the client needs to access some data across them, it is not possible to get it for something like a dashboard. For instance, if the software is designed to allow a manager to see all the orders across the entire week.
Now before you start taking apart the whole API, you can consider using two alternatives. The first being that there is no rule that prevents using multiple URIs which point to the same resource. So, it’s OK to add another URI within the query orders. However, to minimize or remove instances of duplication the top-level ‘orders’ URL can be limited just to GET requests.
The alternative and perhaps the slightly better approach is called snapshots. For instance, the manager wants to check out a few statics a snapshot resource can be created to find and display the information. Some people may find this to be a more efficient approach since you don’t feel like it is querying a database. However, using this approach will require more in-depth knowledge of who the API is being used by.
Auto Translation
We live in a multi-lingual world so why should our APIs be limited to a single language. If you are developing a multilingual application something which we advise that you do it needs to have translations of the internal code too. But how do you manage such a feat? Well, one way is to allow the user of the API to specify their preferred language within the ‘Accept-Language’ HTTP header. For instance, Accept-Language: FR will tell the REST API to translate everything to French automatically.
