Your data model has begun to stabilize and it is time to create a public API for your web application. You realize that it is difficult to make significant changes to your API once it was released, you want the best and as soon as possible. Now, there is no shortage of opinions on API design on the Internet. But, because there is not a popularly adopted standard that works in all cases, you’re left with a bunch of options: What formats should you accept? How should you authenticate? Should your API be versioned?
Versioning the API
It is highly recommended, pulling to mandatory, to put API version and not release APIs without version. Use a simple number to specify the version. If the URL is used to mark the version, put a “v” preceding the version number.
It is the simplest and most effective way to ensure compatibility in the versioning of the API. Specifying it as a parameter or in the request and/or response, leads to an increase in traffic and the cost of computing, since there must be logic to discriminate the different supported versions on the same URL.
Handle errors with HTTP status code
It is difficult to work with an API that ignores the handling of errors, not to say impossible. The return of an HTTP 500 code for any type of error or accompanied by an error trace of the server code is not very useful, besides it can put us in danger before a vulnerability that an attacker wants to exploit.
Use HTTP status codes
The HTTP standard provides more than 70 status codes to describe the return values. In general, we will not use them all, but at least a minimum of 10 must be used, which are usually the most common.
Allow replacement of the HTTP method
Some proxies only support POST and GET methods. For a RESTful API to work with these limitations, the API needs a way to replace the HTTP method. One option is to use the HTTP header “X-HTTP-Method-Override” to overwrite the POST method and thus customize the POST request so that it meets, for example, a DELETE operation.
I hope that this concise guide will allow you to make RESTful APIs with a better design, or improve those that you already have developed, that are generating a new version of the API. For more information about this topic, visit stoplight.