According to a recent Nordic APIs statistics roundup, over 90% of developers are using APIs and they spend nearly 30% of their time coding APIs. This clearly illustrates how important APIs have become for businesses, but also how much impact they have on the workload of IT professionals.
In this post I will dig into the benefits that API design tools bring to your API development process, and look at how you can use Smartbear’s SwaggerHub solution with webMethods API Management.
If you don’t feel like reading, here is a quick demonstration that takes just a few minutes!
Where does API design fit in?
This post is part of a series of technical posts that I announced in New API tools are transforming API Management. In that introduction I used this simple representation of the API Lifecycle.
The API lifecycle is a high level abstraction of the actual delivery process for APIs. Ultimately APIs are software, and our industry has well-established practices like DevOps and CI/CD for software delivery. The next diagram illustrates how the API lifecycle can be mapped to different stakeholders.
The blue circle highlights the parts and stakeholders of the API lifecycle that API design impacts. The API product manager is commonly the main contributor and defines what the API should do and how developers can use it.
What are API design tools good for?
Traditional API development practices often start with implementing business requirements in code and then generating the API specification and documentation from that code. For example, you would develop your Spring Boot microservice, annotate the implementation for OpenAPI and let the specification be generated by the framework. This is what you would call a code-first approach to building APIs.
Code-first API development is quick and well supported by many developer frameworks. But it does have a few downsides too:
- Consumers of the API have to wait for the implementation to finish to get the completed API specification.
- API specifications can be the basis for very rich documentation and a great developer experience, but generated specifications are often limited to the bare necessities.
- Without deliberate upfront planning and design, you run a significant risk of expectation mismatches which leads to costly rework.
A design-first approach to building APIs aims to tackle these disadvantages. With a design-first approach you describe the API in an iterative way that both humans and computers can understand - before you write any code. Every stakeholder participates in the API design to write an API specification that satisfies the business requirement in a way that works for everyone. Having the API specification available early in the process has significant benefits:
- You can use the API specification to create mock servers, making it possible for teams to work in parallel.
- Using API design tools you can create API specifications that improve the developer experience with interactive documentation, code samples, try out features, etc.
- With API design tools it is easier to reuse components across multiple API projects, greatly reducing cost of development and improving the developer experiences across all APIs.
API Design tools come in different shapes and forms. webMethods API Gateway has API design features. But other options are available too, ranging from simple text editors over IDE extensions to robust collaboration platforms. SwaggerHub fits that last category and offers an enterprise-grade solution for accelerating API delivery and quality through collaboration and built on OpenAPI.
Integrating SwaggerHub
There are different options for getting the specifications designed with SwaggerHub into your gateway. You could for example import them manually. However, SwaggerHub supports direct integration with version control systems, which leads to interesting possibilities. I will walk you through an example with GitHub as the developer platform.
- You design the API specification and documentation in SwaggerHub. You get all the cool and nifty features they offer to design the API in such a way that it will be clear to implement and delivers a great developer experience.
- When you’ve finished the design you are ready to make the specification available for the developers. SwaggerHub has a GitHub Sync feature which synchronizes your API specification and optionally generated server code and client SDK with a GitHub repository.
- Then your developers go and do their magic, building an awesome API. As part of their CICD pipeline, they will automate building, packaging and deployment of the service code. In a previous post on using GitHub Actions with webMethods API Gateway I have explained how you can automate the registration and promotions of APIs with GitHub workflows. I’ll use a similar approach here, automatically registering the API in webMethods API Gateway as part of the CICD pipeline.
And that ties it all together! If you’d like to see it all in action, here is a quick demonstration that takes just a few minutes!
