Many actions, which at times may even seem trivial, can be performed to help the developer who is implementing the consumption of APIs to use it correctly, thus avoiding an overload of unnecessary and incorrect calls in addition to not understanding the flows and actions.
Below we will list 10 steps that can assist in the process of ensuring the consumption of APIs and thus their use in an optimized and successful way.
10 steps to ensure successful consumption of APIs
- Extracting metrics
Extracting usage metrics from the executed requests will let you know exactly the usage volume and what is the percentage of Errors X Successes, in addition to identifying major issues of APPs/developer, operation and type of error, and, consequently, implementing actions to improve the experience and usage.
- Constant error alignment
Providing feedback to the developer, with evidences and guidelines for adjustments, will enable aligning the error scenarios, and supplying information to fix the issues. Assuming that your developer makes errors due to some process failure, it is possible to align as soon as possible according to the evidences and guidelines for fixing the errors internally in the development process.
- Monitor executed error calls
In addition to extracting and identifying errors when using APIs, it is also important to conduct constant monitoring. So, it will be an effective action to identify the cause/reason for such errors and also check out if the developer has made the necessary fixes. This action also will assist in item 2, where it will be possible to collect the evidence for alignment with the developer and monitor usability.
- Developer Portal with documentation and inputs about the API
The Developer Portal is the entry for the developer who wants to consume the available APIs and it must be through it that the information and user guides are available.
- Clear and elaborate documentation on the Developer Portal
This will support the entire onboarding process and make understanding clearer. An easy-to-communicate Dev Portal is one that contains both technical and business language, for a wider range of information.
- Inclusion of best practices in the Dev Portal about the use of the API, business rules, possible HTTP Status
Some of the information that we believe is necessary to include in the Dev Portal, as it will support the developer in understanding the rules more objectively, and thus being able to include rules and information in the development itself.
- Return message with clear and explanatory error information
This will make it easier for the developer to understand when an error occurs. Exposing a friendly message when an error occurs, in addition to standardizing HTTP Status, will assist the developer to more easily identify errors and causes.
- Development of recognition of returns on the developer side
For example, the developer needs to identify the error through the http status + error message displayed, and take the necessary actions, thus avoiding continuation of the scenario repeatedly.
- Swagger with quality
A very detailed swagger with the description of the fields, example of values and all the query params will help the developers and reduce the usage “discovery” time.
- Test environment
For simulating the processes that will be executed/used in production. Thus, the developer will be able to carry out the necessary tests and several simulations, without impacting use in the production environment.
These are some points to be aware of in terms of the experience that developers are having when consuming your APIs, whether they are open or private.
Here at Sensedia, we have multiple resources that can help you be more successful with the distribution and onboarding strategies in the APIs to ensure that best practices are being applied properly.