Embracing an API Design First Approach

We work with a lot of companies who are at different points along their API journey. Some are just beginning to see they need an API strategy, while others have entire teams dedicated to defining and implementing one. But no matter where they’re at, we’ve found they’re all looking for ways to embrace an API Design First approach.

What We Mean by Design First

At first glance, “design first” seems to imply that people using other approaches postpone their design or leave the design phase out altogether. This isn’t what we mean by Design First.

Rather, Design First means people write down their API design in a way that both humans and computers can understand. Other approaches may encourage upfront design, but in those approaches the design can’t be used later in automation or developer tools.

Design First means everyone on the team is speaking the same language. It means every tool can leverage the same design. Companies and teams that embrace this approach can bridge the gap between design and development. There are many benefits to this style of API design, including:

• Product-Driven APIs – Teams can include product managers and QA engineers earlier in the process to help shape the API’s features. This helps the team build an API with a product focus.
• Design-Driven Development – API developers can use the API design to drive their development efforts. Automated tools can guide them on what to build and make sure they’re building the API according to the design.
• Working in Parallel – People can start building API clients before the API itself is finished. This allows API consumers, API producers, and technical writers to work in parallel rather than waiting on each other.
• Shorter Feedback Loops – The API team can use automated tools to get faster feedback to validate their design. A team can try out a design and view its documentation as they write rather than waiting until developers deliver working code.
• Helping DevOps – A DevOps team can use the API design to test an API before it’s deployed into production. They can use automated tools to check the implementation against the design rather than checking manually.
• Adapting to Late Changes – Teams can influence the API design throughout the development phase. With the right tooling, they can make design an ongoing and evolving process rather than a step that only happens prior to development.

There’s both short and long-term business value in embracing Design First. Teams start to produce the right software for the right design. Teams work with confidence that they’re on the right path. Companies reduce the risk of putting the wrong software out into the world. And companies start to see their APIs provide more consistent experiences.

Design First contributes to something that’s very important. It blends the design and development phases of software development to allow the phases to influence each other. Companies who use it can adapt quicker to changing requirements—their resiliency to change becomes a competitive advantage.

Challenges of the Code First Approach

Usually when we say “code first”, we mean teams generate the machine-readable API definition from code rather than writing it themselves. They use the generated document as a build asset rather than a design asset. Code First doesn’t mean teams leave out design. Rather it means their design is hidden away in Jira tickets, Confluence pages, or text documents and potentially lost to history.

A team using Code First misses out on the benefits of using their API design throughout the entire development process, not just in writing code. This leads to some potential problems.

• Frustrated Users – If the API documentation isn’t published, is incomplete, or doesn’t line up with the deployed API, API users can become frustrated and go somewhere else.
• The Wrong API – If the team doesn’t have automated tools to guide the design, teams can build and deploy the wrong thing.
• Missed Opportunities – If the team doesn’t have a process to publish their OpenAPI document, other teams will have trouble discovering their API, which may result in duplicated the work and missed opportunities.
• Inconsistent Developer Experiences – If the team isn’t using tools to guide the standards they use, they may produce APIs that have different practices and experiences than other teams.

But to be honest, it takes work for any team to move to a Design First approach. For larger companies, it takes dedicated people focused on guiding the transition. Companies must be intentional no matter their size—this shift to Design First doesn’t happen on its own.

How can Code First teams start seeing benefits of Design First now?

There are some practical things Code First teams can do today to improve the way they work and shift toward Design First.

• Source of Truth – Teams can find ways to use the generated document as more than an asset. They can view their API definition as the source of truth for testing and deployment in their DevOps process.
• API Discovery – Teams can make sure they publish their document to a central place for other teams to discover and try out. This helps them share knowledge and aide others in finding their API.
• Published and Current Documentation – Teams can make sure to automate the process for publishing their document, so the documentation is always up to date.
• Including the Right People – Teams can find ways to include more than developers in the API design discussion. In some cases, they can invite product managers, QA engineers, and DevOps engineers into the API design discussion.

A Code First team can mitigate some of their risks by taking the developer experience seriously and ensuring that they are communicating between teams on what they’re building. They can also use these steps to gradually shift to Design First over time.

How Can SwaggerHub Help?

SwaggerHub can fit into people’s development workflow no matter the approach. We believe it’s important for our product to meet people where they are in their API journey. We provide a lot of tools that can help.

• Design Tools – You can try the SwaggerHub Editor for writing OpenAPI documents, standardization tools for writing consistent APIs, and collaboration tools for discussing API designs.
• Quick Feedback Tools – You can try the API Auto Mocking to get quick feedback and try out a design before the developers have built it.
• Integration Tools – You can try the  Source Control Integration to help get the API design into the development workflow, or the API Management tools to help automate API deployments.
• DevOps and Automations – You can try our SwaggerHub Registry API to integrate SwaggerHub into a DevOps process and build automations that treat SwaggerHub as the source of truth.
• Developer Tools – You can try our Codegen for generating client SDKs to make it easy to consume an API in a software project. It also generates server stubs to kickstart the development process for API providers.

• Open Source Tools – You can try our industry-best open source tooling for OpenAPI, like the Swagger Editor and Swagger UI.

We feel SwaggerHub provides the tools people need to build great APIs, whether they use Design First or Code First.

Getting Started with SwaggerHub

We’re the best platform for API design and API collaboration. We’re focused on making API designs a source of truth throughout the development process. We’re providing the tools companies need to implement their API strategies. We’re here to help people wherever they are in their API journey.

If you’re interested in how SwaggerHub can help you with a Design First approach, take advantage of our free trial.