Published by
In today’s fast-paced digital landscape, creating seamless and intuitive experiences for users is paramount. One key factor in achieving this goal is the effective implementation and integration of APIs (Application Programming Interfaces). At Bottle Rocket, every product that we help our customers design and build relies on multiple APIs. To facilitate a smooth software development lifecycle, we’ve been following and promoting an API Design-First process for several years now. Let’s explore the main concepts of API Design-First, its benefits, and some of the key considerations and best practices for getting started with the process.
The Importance of APIs
Long-gone are the days when software was made to be installed and run locally. These days, software either resides on the internet exclusively, in the form of Software as a Service (SaaS) products, or runs locally on a computing device, but makes heavy use of backend systems to accomplish its tasks. One such method of communication between front-end applications and backend systems and services is via APIs. While there are many different flavors of APIs – REST, GraphQL, gRPC, and more – they all serve the same purpose of allowing the underlying building blocks of an application to talk to each other.
There is an old Steve Jobs quote that I find especially applicable to the importance of APIs:
Steve and Apple understood that getting the core details right is what allows a product to achieve incredible success. At the end of the day, the underlying API is the “soul” of a modern software application and one of the core details that needs to be done right to allow customers to seamlessly interact with its outer layers.
What is API Design-First?
With the incredible importance that APIs play in modern software applications, it’s a logical collusion that incredible care and thought should be allocated to the design and development of its APIs. This is essentially the main idea of “API Design-First”.
You may have heard of its bigger cousin, “API First”, which emphasizes the importance of building the API before the rest of the application. However, API “Design-First” takes this idea one step further by heavily focusing on the design and documentation process before writing code. In other words, we want to take a software development approach where the design and shape of the APIs are considered before any frontend or backend development teams begin their work.
Benefits of API Design-First
Proceeding with an API Design-First approach unlocks several key benefits that ultimately allow you to deliver solutions faster, cheaper, and with higher quality. Because APIs are the backbone of modern software, improving the way that they are designed directly impacts the way they are built and consumed, having a positive impact on all stakeholders in the Software Development Lifecycle (SDLC).
Parallel Development
One of the major benefits of taking a design-first approach to APIs is that it unlocks the ability to develop both the frontend and backend for an application in parallel. Specifically, both teams can develop against a concrete API “contract”, or specification, which enables development to continue with confidence that the two sides of the system will integrate smoothly.
Better APIs
Another major benefit of API Design-First is the ability to naturally create better APIs as part of the process. By spending time in the design phase of an API, stakeholders can provide valuable feedback and insights early in the development process.
This works in many different directions. Teams responsible for the upstream services and dependencies can weigh in about what’s currently possible and the feasibility and considerations needed to achieve the desired goal. Likewise, the front-end teams can provide feedback about the proposed workflow and response formats. All this early and up-front collaboration is sure to surface questions, which the other stakeholders can help solve and provide direction on.
Ultimately, all of this leads to identifying potential issues early, streamlining requirements and workflows, and ensuring that the final product meets the needs of all parties involved. The cherry on top is that you’re also much less prone to needing to perform rework when integrating components or evolving the feature set over time.
Futureproofing
The benefits of API Design-First aren’t short-term, either. In addition to ensuring a smooth development process now, a well-designed API also lays the groundwork for future enhancements and evolution of a product. Standards can be decided upon and implemented up-front, establishing patterns and making it easier for the API to evolve and be maintained over time, all while providing the consistency and reliability that API consumers crave.
With the onslaught of generative AI tools such as ChatGPT hitting the market, never has it been more important to have a well-defined API specification available for your product. Since API specifications are designed to be both human and machine readable, it becomes trivial for these generative AI tools to digest a spec and know exactly how to interact with the service. Simply put, if you want to make the most of AI in the future, making sure that whatever you’re building now can easily and reliably be used by these new tools is of critical importance.
API Design-First Best Practices
As you can see, deciding to implement an API Design-First process in your next product is a no-brainer. However, that’s only half the battle. To provide the most gain, you’ll want to adhere to some of the best practices associated with API Design-First. In no particular order, here are some helpful ideas to start with:
API Mappings
Consider creating visual mappings that describe the relationships between screen designs and the associated API calls. In other words, how does the data and functionality ladder up to the API? We’ve found this to be a great way to “check our work” and make sure that the data and functionality needed by a particular part of an application is readily supported by the API. It also avoids API consumer integration issues such as inconsistent, awkward workflows or missing information.
OpenAPI
There are many specification formats available that allow you to clearly define the capabilities of an API, such as Swagger, OpenAPI, RAML, and API Blueprint. However, over the years, OpenAPI seems to have emerged as the clear winner. OpenAPI is the “v3” version of the older “v2” Swagger specification and is an open-source solution developed and maintained by The Linux Foundation. Unless you already have experience or a specific need to use another format, you should be using OpenAPI to describe your APIs.
Documentation as Code
Treat your API specification and documentation like source code. By making use of standard software development tools such as Git repositories, you can meet developers where they’re at, making it easier for them to contribute to the APIs over time. Markdown documents can also be utilized for API documentation that’s not automatically generated from the API specification itself. Pull Requests (PRs) can also be utilized to ensure that a high level of quality and consistency is maintained as the API evolves over time.
Additionally, CI/CD tools enable API specification “linters” to automatically find and flag issues in the design of an API. These checks can be as shallow as making sure that all endpoints have certain responses defined or can go as deep as to pointing out potential OWASP security violations. Even something as basic as a spellchecker that runs as part of the API design pipeline can help ensure that the handoff to development teams is as pleasant and error-free as possible.
Additional Ideas
With that, we’re just scratching the surface of API Design-First best practices. Some additional ideas to consider are things like mocking API responses and dependencies, setting up proxy services to seamlessly route between live and mocked endpoints, and implementing a style guide to encourage consistency and collaboration. Of course, additional topics such as API versioning and security are table stakes as well.
Essential Tools
When it comes to the tooling required to successfully implement an API Design-First program, much of your existing software development tooling can be reused.
XD handoff can be accomplished using tools such as Figma or Zeplin to help understand the use cases and requirements for the API. From there, API design tasks can be tracked alongside the rest of the development work in a ticketing system such as Jira or Azure DevOps. API specifications and supporting documentation can be stored using your existing Source Control Management (SCM) and their corresponding CI/CD tools such as GitHub, Azure DevOps, GitLab, or Bitbucket. Supporting diagrams that help stakeholders visualize API concepts and workflows can be created in tools such as Lucidchart, Miro, or Visio, and published to a shared knowledge portal or wiki such as Confluence or SharePoint. When it comes time to test and prototype API interactions, often against mock services, API clients such as Postman, Paw, Insomnia, or Fiddler can get the job done.
However, there is likely one essential API design tool that you don’t already have in your toolbox, which is software that facilitates the rapid and complete authoring of formal API specifications. Yes, technically, all you need to get started creating API specs is a text editor, but writing OpenAPI specifications by hand is never really a good idea since it opens you up to all kinds of preventable typos and syntax issues.
If you’re serious about giving API Design-First a try, consider investing in a tool that helps with the authoring process. Tools such as Postman do have some API authoring capabilities built in, but our favorite is by far Stoplight (https://stoplight.io). Their “Studio” editor basically provides a visual, form-based UI that allows you to easily and quickly churn out API specifications without needing to already be an expert in the OpenAPI format. It’s like an Integrated Development Environment (IDE) for creating API specifications. If you’re interested in taking it for a spin, make sure to use referral code BRS10 for 10% off your initial Stoplight purchase. Consider one of the annual plans for maximum savings!
The API Designer
The final important element for any good API Design-First program is the recognition of the need for someone to fill the role of the lead API designer. While it’s possible to spread the responsibility of designing the APIs amongst multiple people, appointing a single person to lead the effort allows you to get more milage out of the process. As the liaison between frontend, backend, and user experience stakeholders, the API designer can help ensure that business requirements come to life in an elegant and seamless way.
Conclusion
Embracing API Design-First is essential to unlocking the full potential of your software development teams and enabling seamless digital experiences to be delivered to customers. By leveraging best practices in the API design process, utilizing API-friendly tooling, and advocating for the importance and consistent stewardship of the process, you can create intuitive and efficient APIs that directly benefit all SDLC stakeholders. All of this ultimately rolls up to better experiences for your customers and better success for the business.
Still have questions? At Bottle Rocket, we’ve successfully implemented API Design-First programs on many projects over the past several years. We would love to continue the conversation about API Design-First and how we can work together to help you and your company achieve your digital experience dreams!
