Design and document APIs faster with Stoplight and webMethods API Management

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. This is why deliberate API design, with upfront planning and understanding of how APIs will be consumed, is becoming increasingly important.

In this post I will dig into the solution that Stoplight.io offers for API design and how you can use it in your API development process with webMethods API Management.

If you don’t feel like reading, here is a demonstration!

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 typically the main contributor and defines what the API should do and how developers can use it.

What benefits does API design offer?

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 has its down-sides:

1. Consumers of the API have to wait for the implementation to finish to get the completed API specification.
2. 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.
3. 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 helps you to tackle these challenges. With a design-first approach you iteratively describe the API in a way that both humans and computers can understand - before you write any code. Every stakeholder participates in the API design to create the API specification that satisfies the business requirement in a way that works for everyone.

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. Stoplight’s platform fits that last category and offers an enterprise-grade solution for API design built around the OpenAPI standard.

Integrating Stoplight and webMethods API Gateway

The centerpiece of the Stoplight platform is Stoplight Studio which makes designing API specifications really easy.

• Design and prototype APIs faster with a visual OpenAPI editor.
• Avoid duplication and ensure consistency by reusing components across all of your APIs.
• Create high-quality API designs by enforcing built-in and custom styleguides.
• Bring API designs to life with automatic mock servers and live previews.

Stoplight Studio also integrates with your favorite Git provider, which conveniently embeds Stoplight into your organization’s software delivery processes. Simply put, the output of a design iteration is an OpenAPI specification in your Git repository. If changes are made to the specification outside of Stoplight Studio, those changes will be synchronized from the Git repository before your next design iteration.

But there is more to the Stoplight platform. The Studio offers no-code or low-code interfaces for various other modules in the Stoplight platform which are open source and can be integrated into your CICD pipelines. Two particularly interesting modules are Spectral’s linting and Prism’s mocking features.

In this demonstration I will show you:

1. How to create a Stoplight Studio project that integrates with GitHub.
2. How to design an API with Stoplight Studio’s visual editors and store the changes in GitHub.
3. Create a CICD pipeline with GitHub Actions that uses Spectral to lint the specification before registering the API with webMethods API Gateway.

What’s next?

If you’d like to learn more about the Stoplight platform, you can create a free account and try it out.

If you’d like to learn more about CICD with GitHub Actions for webMethods API Gateway, check out this article.

Visit original post