There are some good practices and actions that are recommended by our DX team for customers using the APIs to put into practice in order to simplify the understanding of developers during the use.
In fact, these good practices can also be applied in the Developer Portal, to support and guide the developer in this process of use.
On a daily basis, one of the items we have seen facilitating communication and understanding for the development in the consumption of APIs is the correct use of HTTP Status.
The standardization of return codes that the API will provide will help the developer and the integration process, as well as assist the developer in extracting metrics more assertively.
In addition, making this information available on your Developer Portal will make everyone who consumes these calls aware of these standardizations and return representation.
Proper use of HTTP Status
We know that many developers are well informed in all API use processes and these code standards are known worldwide, but making this information available along with the explanation/representation of what each return will mean within their integration will support the developer in understanding possible usage errors more easily and quickly.
Moreover, this allows its own integration available for these purposes to follow these standards determined from the very beginning, even ensuring better monitoring and follow-up of such errors.
Assuming that, in your first API available for consumption, you followed these code standards, but that, for some reason, another team made a new API available without also following these standards. This may generate a divergence in developer usage and will also “mess up” your metrics.
Using this standardization scenario as an example, we can assume, for instance, that your developer makes a POST to insert information, but that this information has already been registered. Leaving only one return as default, for example, through HTTP Status 400 and the error message exposing this scenario will not display this case in metrics, but it will be an overview of the various reasons that can cause the ‘bad request’.
Therefore, you can recommend, for example, HTTP Status 409 (conflict) or 422 (unprocessable entity). This way, the developer will know right away that that certain resource has already been registered and when you, as the owner of the API, go to extract metrics, you will be able to distinguish this case from other possible 4XX more easily and more assertively.
As we have seen, there are several very interesting factors to consider regarding good practices in API use and also in feeding the Developer Portals.
Providing an API goes beyond simply opening an integration, it is necessary to think about the experience of its consumption, and the clearer and more objective the communication is, the better your API will be.
Here at Sensedia, we have teams specially dedicated to this and that can provide various inputs on how to make your resources available. We’ll now recommend a few articles on the subject: