In the past few weeks, we’ve finished the CS-343 semester focusing on designing/implementing REST API calls and interacting with back- and front-ends. During one of our classes, I recall a discussion about the fact that there are no unified across-industry “best practices” for writing API’s. Specific API structures and rules are common within teams but can vary from organization to organization, however there are some general habits and strategies. So I decided to do some searching and focused on a blog post on the website for Swagger, the REST API view/interaction software we’ve been using in class: Best Practices in API Design.
The post discusses some general best practices on creating consistent, well-designed API’s by focusing on three key characteristics:
- Being easy to read, understand and work with
- Being hard to misuse, and in turn more intuitive for users
- Completeness and Conciseness – something which the post acknowledges frequently happens over time as developers build on top of existing APIs
Alongside some other basics on CRUD operations and how they correlate to standard REST API calls (get, post etc.), the post also dives into practices for writing effective call response messages. The codes for responses should follow the HTTP standards, where client-side errors return 400-level (4xx) codes versus server-side errors return 500-level and successful calls return 200-level.
Arguably most important is providing thorough and clear explanations in response messages. For error responses, this entails providing detailed messages describing the error that occurred and suggestions/tips to address and debug it. As a part of this, it’s worth considering putting an example of a successful call to show proper syntax and passed parameters – handholding users will pay off with smoother API interactions long term. To reinforce this, the blog post recommends providing examples for all possible GET responses to demonstrate successful data access calls.
While specific implementations will vary by project/system, these are some good strategies and habits to keep in mind. The importance of providing examples for each individual GET response really sticks out and hits home for me. I can imagine with more complex systems and calls that may contain various request, query or other parameters it could quickly become confusing for users to navigate and access information they need. It seems worthwhile to also provide an example of a successful call in the error response for some specific situations, such as an Error 400 – Malformed Requested → providing an example successful request.
Below, you’ll also find a link to a “glossary” of REST API parameters with explanations on their purpose and uses – a resource I also recently came across and have been finding valuable. If you have any other suggested “best practices” to keep in mind when designing REST API calls, please let me know in a reply or E-Mail.
- Blog Post: https://swagger.io/resources/articles/best-practices-in-api-design/
- Parameter Glossary: https://rapidapi.com/blog/api-glossary/parameters/
From the blog CS@Worcester – Tech. Worth Talking About by jelbirt and used with permission of the author. All other rights reserved by the author.