As the fifth post in MuleSoft’s API Design Best Practices series, author Mike Stowe discusses response handling within your API. Built on a solid foundation, and with comprehensive documentation in place, it is imperative to ensure developers using your API can understand what has happened when something goes wrong. This is achieved by returning accurate error codes with a descriptive error message when a request fails.
Issuing an incorrect status code can negatively impact developer experience which can seriously hinder adoption of your API. For example, the status code 200 means that the request was successful. However, if this code was used to signify that the user is not authorised (which is error code 401), relying solely on the status code would lead the developer to believe the request was successful when in reality it had failed.
Furthermore, even with accurate error codes in place, it is just as important to apply descriptive error messages. In this tutorial, the author describes a frustrating 30-minute experience trying to understand why he was getting a “This call is not allowed” response from an API. After calling support, he was told that his access token was invalid through a simple copy-and-paste mistake. Had the API returned a message stating “Invalid access token”, the author would have immediately understood what had gone wrong and been able to rectify it quickly.
The rest of the tutorial discusses things to keep in mind when building SDKs, especially the interconnectedness of your SDK with your API which adds complexity to updates. The overall idea of this article is to nurture developer relations through considered documentation and support to ensure your API is easy to integrate.