Good RESTFul APIs.

Just a decorative image for the page.

What is a Good API?

Note: While API just means “Application Programming Interface” - this article mostly talks about an Http “RESTful” API that is accessible via the internet and sends back Json.

Table Of Contents

The API is your User Interface

A well-designed API acts as a user-friendly interface for developers, much like a graphical UI does for end-users. Just as an application’s success depends on its UI/UX, the quality of an API can significantly impact its adoption and usability. A clear, intuitive API can make integration straightforward, while a poorly designed one can lead to frustration and increased support requests.

Structuring Internal Codebases

Properly designed APIs not only enhance the external user experience but also help structure internal codebases effectively. They enforce clear boundaries between services, promote reusability, and facilitate smoother maintenance and scaling.

Good APIs will increase how data is stored and raise questions like: “Don’t we need a timezone for that date over here?”, or “does his resource really belong to this package?”.

Enabling Growth and Reducing Support Efforts

When APIs are easy to understand and well-documented, developers can integrate them with minimal assistance. This reduces the number of support requests and allows your team to focus on more critical tasks. This is especially important when your organization is growing and you have to decouple growth from hiring new support specialists. Good APIs will allow users and implementors to just go ahead and implement your API in a true self-service way.

The First Step: Establish API Guidelines

If your teams don’t have established API guidelines, this should be your top priority.

Don’t reinvent the wheel!

In my experience, adopting a set of guidelines with specific exceptions can be highly effective. For instance, you might follow Zalando's API guidelines but make an exception for property naming by using camelCase. This approach keeps internal documentation and discussions concise and focused. While designing API guidelines can be time-consuming, remember that your primary goal is to develop and deliver software efficiently.

The “API First” Approach

At companies like Zalando, the “API First” approach ensures that APIs are thoughtfully designed before implementation begins. Here’s how it works:

  1. Draft the OpenAPI Definition: Start by drafting the OpenAPI specification for the new endpoint. This includes detailing the endpoint’s purpose, expected request and response formats, and any necessary parameters. Make sure to describe the endpoint and add examples. Don’t implement any code at this stage.

  2. Get Feedback: Submit a pull request (PR) with the draft to an API Chapter or similar group within your organization. This can be a simple Teams or Slack group. This practice fosters collaboration and helps ensure the API is intuitive and aligns with organizational standards.

  3. Iterate Based on Feedback: Use the feedback on the PR to refine the API definition. This process might involve improving descriptions, simplifying endpoint structures, or clarifying payloads.

  4. Begin Implementation: Once the API design is approved, proceed with implementation. This ensures that the development process is aligned with the agreed-upon specifications.

The Importance of Good API Documentation

Seniority and Documentation

In my career ladder I make it explicit: “Good documentation and writing easy-to-understand API descriptions is a clear sign of a senior developer.”

If you have an endpoint called “appointment” with the description “creates appointment” (no examples, no further details on business logic) then this is not good enough. It’s a sign that the author is not a senior engineer yet.

“Writing well” is crucial because clear documentation helps users grasp complex concepts and use APIs effectively. If you’re finding this challenging, seek mentorship and support to improve your skills. There’s even an excellent book about the topic!

Best Practices for Good API Documentation

  • Avoid Acronyms: Use full terms to prevent misunderstandings.
  • Put Yourself In the Users’s Shoes: Explain concepts clearly and anticipate potential confusion. Describe business logic well and in simple terms. Start with the basics. How would e.g. a user get an auth token?
  • Use Visuals: Diagrams can simplify complex interactions and illustrate data flows.
  • Provide Use Cases and Examples: Explain when and why an endpoint should be used with practical examples.
  • Include Code Samples: Offer examples, such as curl commands, to demonstrate requests and responses.

Keep a Single Source of Truth

Managing API documentation can be challenging, especially as systems grow. It’s tempting to maintain separate documents for technical specifications and user guides, but this can lead to discrepancies and increased maintenance overhead.

Unified Documentation

  • One Source: Use a single platform, like OpenAPI, to document your API. This ensures consistency and reduces the chance of documentation diverging.
  • Enhanced Visualization: Tools like Redoc can transform OpenAPI files into user-friendly documentation, making it easier for developers to navigate and understand your API.

Conclusion

Creating beautiful Json RESTful APIs requires thoughtful design, clear documentation, and collaboration. By adopting an “API First” approach, focusing on excellent descriptions, and maintaining a single source of truth, you can build APIs that are not only functional but also a pleasure to use. Remember, your API is your product’s interface to the world — make it count :)

More

Related posts

Imprint | Privacy Policy