By: Daniel Ors, Gabe Martinez
In this guide, we will walk through how to go from the need for an API, through its design and documentation, and to its subsequent implementation. This is an entry in our API Design and Documentation Series. If you haven’t read our Attributes of a Quality API installment, I recommend you start here.
Designing and implementing an API can be a daunting task. Our goal is to provide you with a comprehensive guide on how to approach designing an effective API and its documentation. To do so, we will break the process down into 4 steps. The first step in your API’s design and development is to precisely define what is needed out of your API.
Your API needs to provide the right functionality for its consumers which means you need to rigorously define what that functionality should be. Accurately defining the purpose and scope of your API will provide you with crucial guidance on it’s design and implementation. The purpose of your API should be determined by considering the problem that you are trying to provide a solution for. To elaborate, you should consider who the API will be used by (who needs the solution) and what they want to do with your API. Ensure that you have acquired the necessary domain knowledge for the problem space and communicate with the parties who will utilize your design as well as the parties who are affected by your design. These are the consumers of your API and thus, they will be able to assist you in collection and clarification on the use cases and requirements of your API. This communication is key to gain perspective on what your design should offer. We also strongly recommend that you research existing solutions and learn from their strengths and weaknesses. Rigorously collecting and detailing this information will give you what you need to design your API in a way which will be both comprehensive and effective.
Now that you have determined the purpose of your API and its requirements you can start to transform this list into your design specification. To begin, filter and refine the list of requirements and use cases that you want to cater to. Incorporate initial features and potential future enhancements into your considerations. Detail the overarching workflows and usages. Outline the expected behaviors and business logic of the API. Understand and document potential dependencies and interactions, both internal and external. From here, Define models, their relationships, and how the API will interact with them. Important: Document this information for future reference. Utilize tools available to you. Entity Relationship diagrams, flow charts, and other visual aids are invaluable.
With this information in hand you will find that your specification starts to construct itself. Start to document your design and specifications with best practices in mind. Check out our API Design Best Practices guide for a refresher. Once you have a specification detailed refer back to the information you have organized and adjust if necessary. Important: Your design will change over time as you document and implement the API. Use your knowledge base and an Agile Methodology to keep it flexible enough to cater to changing requirements.
Some may wonder why the documentation comes before the implementation. But this is a crucial step. Documenting your API specification will more often than not bring your attention to design modifications that can or should be made. Furthermore, it will help guide your implementation to be effective and efficient. Once again, tools like API Description Languages (OpenAPI/Swagger, RAML, etc.) or API development platforms like Postman, can be quite beneficial. Not only will they increase the efficiency of your documentation process but they can help you identify these modifications. There are many tools that will help you build your API documentation, and they include a suite of useful capabilities. Some of these capabilities include, helping you publish your documentation, providing consumers with test beds, building automated testing cases, or even generating code as a baseline for your implementation. Determining which tool to use varies but we highly recommend you research how they can benefit your documentation process.
Well-Defined, Discrete Endpoints
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.
Finally, you now have your API specification thoroughly defined and well thought out. It’s time for the implementation. Of course, the details of your implementation are specific to your API. However, there are some common best practices when it comes to implementing your API. Consider implementing Contract Testing. Throughout your development, contract testing will help you catch and handle any inconsistencies between your implementation and your design. APIs will almost always change over time. Keeping your design patterns consistent as your API evolves is vital for the health of your API specification and corresponding documentation. Similar to a code style guide, you can create a Design Style Guide to protect the longevity of your API. In addition to consistency, a style guide will also ensure future design decisions and development are unambiguous and smooth. Refer back to our API Design Best Practices guide for more examples of what kinds of things you can include in a design style guide.
Defining an API specification is no simple task. It is for this reason that designing one will surely not be concluded once you have published your API for its initial consumers. Much like all software development, it is an iterative, Agile process, and your API will be refined and augmented over time. Maintaining your API is the next part of the design journey. Be open to feedback from your consumers and refer back to the process and design standards you set out for your organization.
This series will be continued in next week’s installment, API Documentation.