What is an API and how do you design it? 🗒️✅

Summary

This video from GKCS dives into the principles of designing effective APIs. It emphasizes the importance of clear documentation, function naming, and parameter selection. The script discusses common pitfalls, such as improper error handling and response design, and offers insights on optimizing API performance. It also touches on the balance between consistency, atomicity, and the potential side effects of API actions, providing a comprehensive guide for software engineers to create efficient and user-friendly APIs.

Takeaways

• 📚 APIs are documented ways for external consumers to interact with your code, focusing on how to use the code rather than its internal workings.
• 🔍 When designing an API, consider the context and functionality it serves, such as 'GetAdmins' for retrieving admin details from a WhatsApp group.
• 🛠 Errors in APIs should be meaningful and relevant to the operation, like handling non-existent group IDs or deleted groups.
• 🔑 APIs should have clear naming conventions that reflect their functionality, avoiding misleading names that don't match the operation performed.
• 📝 Avoid over-parameterization in APIs; only include necessary parameters to prevent confusion and maintain clarity.
• 🔄 Optimize APIs by reducing the number of calls made to other services, but ensure the API's name and parameters accurately reflect this optimization.
• 📈 Be cautious with the amount of data returned in API responses; too much unnecessary information can lead to network inefficiencies and confusion.
• 🚫 APIs should avoid side effects, ensuring that each operation is atomic and does not perform unintended actions beyond its intended function.
• 🔄 For large responses, consider using pagination or fragmentation to break down the data into manageable parts for the client.
• 🤔 Consider the need for consistency in API responses; sometimes a slightly outdated response may be acceptable depending on the use case.
• 📉 In high-load scenarios, consider service degradation strategies such as caching or reducing response size to maintain performance.

Q & A

What is the primary purpose of an API according to the video?

An API is a documented way in which external consumers can understand how they can interact with your code to get their work done, without needing to know how the code works internally.

Why is it important for an API to have a clear and concise name?

The name of an API should clearly define the action it performs and the parameters it requires. This helps in avoiding confusion and ensures that the API's functionality is easily understandable to the users.

What should an API function like 'getAdmins' return if it is designed correctly?

If an API function is named 'getAdmins', it should return a list of admin objects. It should not return additional unrelated information, as this would make the API's purpose unclear.

How can the design of an API be optimized to reduce the number of IO calls?

Optimization can be achieved by including additional parameters that provide the service with more information upfront, reducing the need for the service to make multiple queries to other microservices.

What is the significance of the response object in an API design?

The response object should contain only the necessary information that the caller needs. Overloading the response with too much information can lead to increased network requirements and confusion for the API user.

Why is it considered bad API design to include too many errors in the API definition?

Defining too many errors can lead to an overly complex API that is difficult to use and maintain. It's important to focus on common expectations and responsibilities that the API should handle.

How should an API handle unexpected input types, such as a non-integer group ID?

Instead of defining an error for every possible incorrect input type, the API should define the expected data type and handle errors where it is the API's responsibility, such as when the group does not exist or has been deleted.

What is the role of versioning in API design, as mentioned in the script?

Versioning, such as using 'V1' in the API path, allows for the evolution of the API over time without breaking existing functionality. It enables developers to make updates to the API while maintaining compatibility with older versions.

Why is it not recommended to mix routing information with the action in an API?

Mixing routing information with the action can lead to ambiguity and a poorly designed API. It's important to keep the action clear and separate from the routing to ensure the API is intuitive and easy to use.

What are some strategies for handling large responses in an API?

Strategies for handling large responses include pagination, where the client requests chunks of data, and fragmentation, where the server breaks the response into multiple parts and sends them individually.

How should an API handle side effects, such as creating a group while setting admins?

An API should avoid side effects by keeping actions atomic and specific. If multiple operations are required, they should be broken into separate API calls to maintain clarity and prevent unexpected behavior.

What considerations should be made regarding data consistency in API design?

The API designer should consider whether perfect consistency is necessary or if eventual consistency is acceptable, based on the use case. This decision can impact performance and the user experience.

How can service degradation be used to improve API performance under load?

Service degradation involves reducing the response size or complexity under high load, such as serving data from cache or returning only essential information, to ensure the API remains responsive and stable.