API Design Anti-patterns: Common Mistakes to Avoid in API Design

Sarmitha Krishnagobal

Application Programming Interfaces (APIs) are the messengers between different applications. They allow software components to communicate and exchange data, powering the interconnected world we live in. A well-designed API is clear, efficient, and easy to use, while a poorly designed one can lead to confusion, frustration, and wasted development time. This blog discusses ….

What is an anti-pattern?

Wikipedia defines a software anti-pattern as:

“In software engineering, an anti-pattern is a pattern that may be commonly used but is ineffective and/or counterproductive in practice.”

Simply put, an anti-pattern is something that seems like a good idea initially but ultimately causes problems. By understanding these pitfalls, you can create APIs that are robust, maintainable, and developer-friendly. These are not bugs but rather design choices that can lead to long-term problems. Let's delve into some common ones!

Common anti-patterns

• Focusing on Implementation Details Instead of Resources (RPC-style APIs)
  Remote procedure call (RPC) style APIs are a common anti-pattern in RESTful API design. These APIs expose methods that map directly to the underlying implementation, rather than focusing on resources. This makes the API rigid and difficult to evolve.


• Over-Engineering for Unforeseen Needs
  This occurs when developers try to anticipate every possible use case and build a complex API to accommodate them. Over-engineering leads to bloated and difficult-to-use APIs, making maintenance a nightmare.


• Tight Coupling Between Client and Server
  Tightly coupling the client and server can make the API inflexible and difficult to change. This strong dependency between implementations makes the API brittle and hard to evolve without breaking clients.


• Lack of Versioning
  Not versioning your API can lead to issues when you need to make breaking changes. Without clear versioning, managing updates and ensuring backward compatibility becomes a significant challenge.


• Inadequate Documentation
  Poorly documented APIs can be difficult to use and lead to confusion for developers. Good documentation provides clear descriptions of each method and the resources they return. It should help developers get started quickly rather than hunting through dense libraries of docs. Document your API well using tools like Xapi and Swagger.


• Misusing HTTP Methods
  HTTP methods like GET, POST, PUT, and DELETE are meant to convey the intended action of a request. Overloading these methods, or using them in ways that don’t match their intended purpose, can make the API confusing and difficult to understand.


• Lack of Error Handling
  Failing to handle errors properly can lead to a confusing and frustrating experience for developers using your API. Providing meaningful error messages and appropriate status codes is crucial for a good developer experience.


• Tunneling Through a Single HTTP Method
  Your API is a collection of methods. Tunneling everything through a single HTTP method, like GET or POST, can make the API inefficient and difficult to manage.
  • Tunneling through GET: GET should retrieve a representation of a resource identified by a URI. Misusing GET for actions like deleting or finding customers by encoding parameters in the URI is a common anti-pattern.
  • Tunneling through POST: POST carries an entire body, not just a URI. Using POST for varying messages to express different intents is another common anti-pattern.
• Ignoring Caching and Revalidation
  Preventing caches from caching everything, and not supporting efficiency and revalidation, is a missed opportunity. Proper caching is crucial in RESTful APIs, enhancing performance and efficiency. Delegate cache header generation to infrastructure like Apache HTTPD. Clients should utilize caching to avoid redundant requests, using proxies like Squid. Web caches reduce latency by serving responses faster and lower network traffic by reusing data, saving bandwidth and costs.


• Inconsistent or Misleading Status Codes
  Misusing or failing to use proper status codes when sending responses can lead to poor communication between the client and server. While many are familiar with 200, 404, and 500, there are many more codes that, if used correctly, provide richer communication.


• Misusing Cookies
  Using cookies to propagate a key to some server-side session state violates REST principles and can lead to security issues. It's essential to manage states appropriately without misusing cookies.


• Overexposing Database Schema
  Exposing your database schema directly through the API makes it inflexible and difficult to evolve. An API should abstract the underlying data model to provide a stable interface for clients.


• Missing Hypermedia Links
  The absence of links in representation means the API is not fully RESTful. Hypermedia links are essential for guiding clients through the available actions.


• Neglecting MIME Types
  Ignoring MIME types reduces the flexibility and self-descriptiveness of the API. Proper use of MIME types is crucial for clear communication about the data formats used.

Common code design anti-pattern

• God Class/Object: A single class or object handles too many responsibilities, violating the Single Responsibility Principle (SRP).
  
• Spaghetti Code: Unstructured and tangled code with poor separation of concerns.
  
• Magic Numbers and Strings: Using hardcoded values without meaningful names.
  
• Yoda Conditions: Reversing the normal order in conditional statements.
  
• Excessive Interface Complexity: Interfaces that are needlessly crowded and complex.
  
• Excessive Use of the Singleton Pattern: Overuse of the singleton pattern across many classes.
  
• Primitive Obsession: Using primitive data types excessively instead of creating meaningful classes.
  
• Copy-Paste Programming: Reusing code by copying and pasting rather than abstracting and reusing properly.
  
• Cargo Cult Programming: Using code or patterns without understanding how they work.
  
• Golden Hammer: Over-reliance on a single tool or pattern, applying it to all problems.
  
• Boat Anchor: Keeping obsolete or unused code in the codebase.
  
• Dead Code: Code that doesn't do anything or its purpose is unclear.
  
• Proliferation of Code: Adding unnecessary layers of abstraction or objects that serve no real purpose.
  

Conclusion

By being aware of these anti-patterns and actively working to avoid them, you can design APIs that are robust, maintainable, and easy for developers to use. This will lead to more efficient development processes and more successful software projects.

References

1. REST API Design Patterns and Anti-Patterns: A Developer’s Guide for Young Developers
2. REST Anti-Patterns
3. Web API Design Anti-Pattern: Exposing your database model
4. Anti-patterns that every developer should know

Sarmitha Krishnagobal

Senior Software Engineer at X-Venture