Every modern web application we use today leverages APIs as a central nervous system for interactions. A poorly designed API impacts developer productivity and application performance. In this blog, we have compiled 6 common mistakes we have seen in API design.

Google Cloud Platform provides a suite of cloud computing services for building, deploying, and managing applications and infrastructure on Google's global network. Developers can learn about cloud-native development, machine learning, and big data analytics to leverage GCP's scalable and reliable cloud infrastructure for their projects.

Google Cloud

A poorly designed API tends to create a similar experience for a consumer developer. Well designed APIs make it easy for consumer developers to find, explore, access, and use them.

RESTful web API Design best practices

<code>A great article to read about RESTful web API's</code>

Actually, there is a 7th common mistake to avoid in Web API design: calling it RESTful when it is simply an HTTP API.
This should be mistake n. 0

This article, published on November 30, 2022, by Varun Krovvidi and Geir Sjurseth, focuses on avoiding common mistakes in RESTful web API design. The authors compare a poorly designed API to a “ready-to-assemble” table delivered without assembly instructions, stressing the importance of clear, user-friendly design.
The six common mistakes highlighted are:
<ol>
<li>
Thinking Inside-Out vs Outside-In: The authors advocate for an outside-in approach, focusing on customer experiences and needs rather than merely exposing internal systems. They suggest engaging with customers to understand their use cases and tailor API responses accordingly.
</li>
<li>
Making APIs Too Complex: Simplicity is key. The API should be easy to use without requiring users to learn a new system. The authors recommend testing the API’s usability and continually refining it to ensure it remains user-friendly.
</li>
<li>
Creating “Chatty” APIs with Too Many Calls: To minimize operational costs and improve efficiency, it’s important to reduce the number of API calls. This involves designing APIs that aggregate multiple functions into fewer calls, possibly using technologies like GraphQL.
</li>
<li>
Not Allowing for Flexibility: The authors suggest offering flexible API endpoints that allow users to filter response properties, sort and paginate results, and use mature compositions like GraphQL to customize data retrieval.
</li>
<li>
Making Design Unreadable to Humans: It’s crucial to keep API designs simple and intuitive, as developers often interact with the API contract before delving into detailed documentation. Clear property names and straightforward structures are recommended.
</li>
<li>
Knowing When to Break RESTful Rules: While adhering to RESTful principles is generally beneficial, the authors note that user experience should take precedence. Occasional deviations from RESTful standards are acceptable if they result in a more user-friendly API.
</li>
</ol>
The article concludes with a mention of a comprehensive guide created by Google Cloud’s API management product, Apigee, which encapsulates their extensive experience in designing and managing APIs at scale.