Designing REST APIs with Stoplight
Milos Svana
2 years ago
A well-designed API is both an important business driver and a must if you want to split your software product into smaller modules. Whether you decide to deploy your app as a set of microservices or separate the client-side rendered frontend from the backend, you need to think about how the individual components will interact with each other.
Externally, a high-quality API can be a huge selling point. This is especially true in the B2B world; letting customers access your service programmatically can help them improve their products or create something completely new. Creating platforms for others to use is one of the best ways to support innovation.
Because of these factors, tools for accelerating API development provide a lot of value. In this article, we’re reviewing Stoplight, an online platform for designing, documenting, and testing APIs based on the OpenAPI specification.
What is Stoplight?
At its core, Stoplight is an OpenAPI specification editor. Unlike Swagger Editor or Apiary, you use a graphical editor instead of editing the YAML specification file directly. Because this work can be done by simply filling form fields, you don’t need to know the OpenAPI specification format in detail. You install and use this editor on your local machine with the name Stoplight Studio.
Stoplight also has a commercial SaaS offering which includes GIT integration, a mock server, automatic documentation generation and publication, or a shared workspace for multiple users.
We think Stoplight Studio is a good choice for individual developers and small teams. As your team grows and collaboration and cooperation difficulty increases, you might benefit from the additional features provided by the online version. In our experiments, we went with the second option and signed up for a free online workspace limited to one API project and three users.
Our use case
To test Stoplight’s capabilities, we considered a simple use case based on a personal side project; a simple web application for a fundamental analysis of publicly traded stocks.
This app lets you list companies in different industries and calculates various fundamental metrics such as price-to-earnings ratop, return on equity, profit margin, and dividend yield. It also implements the TOPSIS method for multiple criteria decision analysis, which calculates the overall ranking of each company.
The app is written in Python as a server-side rendered monolith. To increase the interactivity of the user interface, we split the application into a JavaScript frontend and a Python backend. We also want to use the data provided by the application in other tasks, such as data analysis. We addressed both requirements by developing a REST API.
To satisfy all of our requirements, we need to implement four REST endpoints, each using JSON as data exchange format:
- /industries: provides a list of industries to select from,
- /companies/{industryID}: returns a list of companies in a given industry with all fundamental metrics and the final TOPSIS score,
- /last-price/{industryID}/{year}: returns last close prices, as well as the sum of all dividends for all companies in a given year. This data is useful for developing and testing various mathematical models that describe the behavior of stocks
- /weights: sets weights of different metrics in a given industry. These weights are applied during TOPSIS score calculation and express the importance of different metrics when determining the overall rank of a company.
Designing the endpoints
We started by creating a new project and connecting it to a GitLab repository with a separate branch for API specification. Stoplight then cloned the repository, and we gained access to all files just as you would on your desktop.
First, we specified the simplest /industries endpoint. We only needed to define the response body in case of success (code 200). We used an individual industry model and defined all properties expected in the response:
We used this model definition to specify the response format as an array of objects matching the Industry model:
Because we used the connexion Python library to implement the API, we also specified the operation ID. The value provided determines the Python function implementing the endpoint.|
We repeated the same process when specifying the /companies/{industryID} and /last-price/{industryID}/{year} endpoints. We also needed to specify path parameters that let a user choose the industry and year of interest.
As it’s possible a user might enter an industry ID or a year for which we have no data, we specified the 200 SUCCESS response, and the 404 NOT FOUND response. Fortunately, it’s easy to add responses for different status codes.
Finally, we defined the /weights POST endpoint. Since the user is now sending data to the server, we had to specify the request body. The request needs to contain the ID of the industry whose weights we want to modify and the weights themselves. We again created a model and told Stoplight that we wanted to use this model as a request schema.
Finishing touches
After specifying our last endpoint, we needed some sort of access protection. Because you can choose between various types of security schemes and apply them either globally or only to selected endpoints, we used a simple solution; ask the user to provide an API key as a request header. For more serious applications, you can use OAuth2 or OIDC.
The last step was to create a Markdown document describing an example workflow, something that couldn’t be generated directly from the API specification. Stoplight includes an integrated Markdown editor with a lot of extensions to the standard syntax. We included a Try It element, which lets the user make an API request directly from the documentation page.
After each change to the API specification, we committed and pushed our modifications to the GitLab repository. The API developer could then pull the code on their machine and work on the implementation.
Once the API was specified, Stoplight automatically generated API documentation that included both automatically generated endpoint descriptions and the workflow example we wrote. We easily changed access rights, and made the documentation public so we could share it with the world.
Conclusion
Stoplight is definitely an upgrade from the lengthy task of writing an OpenAPI specification by directly editing the YAML file. The UI was easy to work with, and significantly shortened the process of API specification, as we didn’t have to constantly browse the OpenAPI docs.
We also greatly appreciate the GitLab integration. While we were designing the API, we were also implementing some of the endpoints. Because everything is stored in the same repository, the synchronization between the specification, implementation, and documentation was seamless.
Some things to consider about Spotlight: they don’t offer a paid plan for very small teams or individuals. The cheapest plan is $79 a month and includes access for five users. As we already mentioned, the Stoplight Studio desktop app might be a better choice for these use cases. Our team would have also appreciated the ability to switch between different OpenAPI versions, as well as an option to connect a project to a GIT repository after its creation.
Even with these issues, Stoplight delivers on its promises. We think it truly can speed up API development. Features like documentation sharing can help other teams and organizations integrate your API into their components or services, and further enhance value creation down the road.