API Design – Attributes of a Quality API

An essential aspect of our massive software world is collaboration. Everything from open source software communities, product integrations, and even microservice communications require collaboration to be successful. Software, and its continued development, rely on the collaborative efforts of those generating it to truly scale into large user adoption. When it comes to communication about software and its development, effective APIs (Application Programming Interfaces), and their corresponding documentation, are crucial to the development of a successful application. In this series we will cover the core attributes of a quality API as well as how to construct effective APIs that support efficient adoption both internally and by external 3rd-parties.

An API is a defined method of interacting with a specific software application describing standardized request formats and what to expect in return for each request type. Since the format for requests is frequently strictly defined, it makes it essential that the documentation is clear, unambiguous, and accurately updated over time. This allows developers to work with unfamiliar systems in a standardized way with zero to minimal involvement from the creator of the API itself. If you’re interested in reading more about the basics of APIs in plain English, FreeCodeCamp has an excellent blog post on the subject.

Over the coming weeks we’ll be taking a deep dive into the key components of designing a successful API — from how specific API attributes make them compelling and easy to work with, to creating your own starting point for an API, as well as an all comers’ guide to how to use an API. We will begin with an examination of the Attributes of a Quality API, then the ins and outs of API Design, and conclude with a deep dive into how to Document your API to maximize its potential and usage.

Quality APIs are identified by several notable attributes:

• Clear Purpose
• Strong Documentation that is Easy to Understand
• Well-defined and Discrete Endpoints
• Rich Data that Presents Significant Value to the Developer and End User
• Potential for Extensibility in the Open Source Community
• Conform to an Established Conventional API Architectural Style (e.g. REST, GraphQL, RPC, Falcor, etc.)
  • How these concepts help craft more maintainable APIs
• Strong Community Supporting its Development via Active Repository Management
• Standards for Maintaining
• Graceful Error Handling
• Solid Security Practices

An API does not require all of these attributes to possess quality or potential, but the very best APIs all adhere to these principles when building out their functionality. If you are getting started with your API, these are clear goals to strive for in getting it off the ground.

Documentation of functionality that is easy to understand is critical to the success of any API. It is essential that the documentation is also not overly succinct in providing understandable instructions, but rather balancing detail with clarity. Without documentation, an API will be nearly impossible to access, and it will be difficult to parse what data, endpoints, or feature frameworks are available to use. This is a frequent issue with closed APIs, where the core users are a limited group of developers that hold all the keys to the castle in terms of knowledge. In this scenario, when new members of the team are introduced to the API, it is unlikely that quality contributions will be produced by the new developer unless the API is well-documented. Person-to-person knowledge transfer is a poor substitute for clear documentation, as clear documentation will always allow for a more transparent and complete picture to be communicated and provides a persistent resource available for reference.

Many APIs allow significant overlap in their data and endpoints, which, depending on the subject matter, may be appropriate. However, distinguishing between data areas has value in charting out your API. Discrete endpoints will prevent developers from getting bogged down in individual features, digging down into infinite JSON soup for applicable data for their use case. This improves usability significantly for your audience.

It is important to design and define these endpoints so that developers will have clear expectations for access and delivery of data. For example, if you have an API that routinely updates current information about a company in its own endpoint, and has a separate data endpoint for employees, it is better to only allow end users to request employee data from the top level employee endpoint (over which you will have more fine-tuned throttling control), rather than having unrestricted access to a separate api/company/employees endpoint. By restricting access to specific endpoints and resources, it will prevent misuse of your dataset and API, and improve the cost of hosting and maintaining it. This can be achieved by including clear rate limits for each endpoint in your documentation along with your authentication protocol for accessing the API.

Without data that presents value to the developer and the user, an API will surely wallow in obscurity — whether it is being built as a personal project or for an organizational purpose. If there is a single use case for the API you are thinking about, that clearly does not exist yet, it is far more likely that a parallel or adjacent API will be available to support development of your idea. Extending that API’s functionality to include yours may also present a more significant value-add to your own resume or organization’s reputation in the marketplace.

Without future potential for innovation, APIs will likely become largely stagnant and more focused on issue handling rather than providing room for growth. It is important to keep an eye on the horizon for the roadmap you envision for your API, or what the community suggests would represent quality additions to the feature set. Your stakeholders — whether they are private clients or the open source community — will have a vested interest in contributing to your API’s improvements and future viability.

When you invest in following a particular API architectural pattern, it also improves the ability of your own engineers, as well as any potential open source developers, to maintain and extend the functionality of your application. This presents a very strong value-add for your organization’s product and its viability as a solution in the long-term.

Using accepted conventions of API style will also aid in its long-term viability and maintainability. In conforming to a pattern, a wider range of developers and engineers will quickly be able to jump in, identify solutions, and become a key contributor. It will aid in developer retention and overall productivity — the easier and more rewarding you make it for individuals to contribute and be an active member of the community, whether open or closed source, the more likely you are to reap exponential rewards.

Using a heavily trafficked versioning tool such as Github or GitLab will also encourage growth opportunities as they increasingly move to a more sophisticated social format for hosting code repositories, particularly open source repositories.

Setting baseline standards for your API is key to ensuring quality maintenance and fulfillment of the product roadmap. It will also make it easier for developers to contribute, as clear expectations will be present for issue resolution as well as feature requests.

Your standards should include several key points — a style guide for code, expectations for contributing, resources required, and rules for communication along with key maintainers.

A style guide will make it clear which specific conventions should be followed in submitting contributions to the codebase. This should include basics such as standard naming conventions, giving priority to commenting new code with sufficient detail, and best practices for specific syntax within the majority programming language being used in your API. Airbnb’s style guide for JavaScript is an excellent example of a strong syntaxical standard.

Your section on expectations for contributing should demonstrate what a proper contribution process will look like — how to identify a suitable open issue to address, whether tests are required, and general timeframe for when to expect approvals or responses from key maintainers. (ex: “Our team spends about 10 hours per week on this project, average response time is 5-7 days.”)

A section covering the resource requirements to get started maintaining will also encourage developers to invest their time — as it will lower the bar to contributing significantly. By documenting your processes and what tools are used by the core team, it will be easier for new contributors to quickly get comfortable with the code and complete their submissions. This is an opportunity to document any existing known issues for developers in working with the project’s standard resources, allowing others to suggest new solutions from their own experience.

Rules for communication will provide clear guidelines for what should be communicated in the contribution process — from reasonable pull requests to what is allowed in the slack/gitter channel for the project. One key requirement that is common to most shared projects is that all decisions, support requests, or feature requests should be submitted in public channels, so that transparent communication is present to all involved. These standards will streamline moderation and management of project channels. Along with these guidelines, a list of key maintainers and project managers should be included. This will add points of contact to relieve pain points if the standard contribution process does not proceed as expected. 

Homebrew’s open source repository follows these principles and provides excellent examples with their Code of Conduct and Contributing Guide.

As your primary audience and user base will be developers, it is important that you provide for detailed error handling along with graceful exiting. It will be a far more dev-friendly experience to end the terminally errored process when it reaches the error state — using conventions such as try/catch blocks to end the connection or request/response operation. It is also key to use specific error handling messages that are informative, concise, and provide the correct level of detail to enable successful troubleshooting.

In order to protect developers, users, and yourself from exposed and non-encrypted connections where API keys and other secrets could be easily transcribed, you should make it a requirement to use security practices such as SSL-only connections and using secure authentication methods such as OAuth to verify access.

If you’ve followed these key steps in building your API, congratulations! You’ve very likely created a strong application that will encourage future development, extension, and user growth. The most critical next step to take is to continue to invest time in cultivating your API’s contributions and release roadmap. Focusing on maintaining the release cycle will ensure continually increased quality of service for both developers and end users.

This series will be continued in next week’s installment, How to Design a Robust API.

By: Daniel Ors, Gabe Martinez