Tips on using Stoplight for API design for API Builder – updated

In a prior blog post we looked at using Stoplight with API Builder and described some tips. There have been many changes with both products since then and this blog post will highlight updated tips and will supersede the prior blog post.

What has changed?

Recall that we are using Stoplight to design the API and then we are exporting the design specification as an OpenAPI specification (OAS) into API Builder and then building the API functionality in API Builder. This is part of an API-First approach to building APIs.

The main enhancement recently to API Builder in this area is that it now supports OpenAPI out of the box.

Some examples of using Stoplight and API Builder for API-First API design and creation are shown in the following blog posts:

• An API-First stock watchlist example using API Builder
• An API-First sentiment analysis API using API Builder

Tips on using Stoplight for API Design for API Builder

The tips are as follows:

While Stoplight supports OAS 2.0, 3.0 and 3.1, API Builder currently only supports 2.0 and 3.0. When you are creating your API in Stoplight don’t select 3.1

Even though API Builder supports Basic, APIKey and other API security schemes, OAS security definitions are not honored by API Builder. However, they should be setup accordingly in Stoplight and API Builder so the OAS spec is accurate and can be used in other tooling chains (e.g. Postman, API GW, …). For example, if you want to use API Builder’s API Key authentication, then set it up properly in Stoplight, namely create an APIKey security Scheme with key name apikey sent as a header and make it Global:

API Builder runs on port 8080 by default and requires a `/api` prefix on all paths. To accommodate for this, you can edit the default server for localhost, port 8080 and add an `/api` suffix. Also, you should update/add more servers after deployment of your API Builder Docker container

When you are ready to move over to API Builder, export your API from Stoplight

If you have relative reference ($ref) errors on API Builder import (next step), you may need to export as dereferenced to overcome:

Then import the file into API Builder and create your flow(s)

If you later modify your API specification in Stoplight you can export the modified API specification and use the API Builder Update feature to update your API and make any necessary changes

Summary

Stoplight and API Builder can be used together to create OAS2 and OAS3 REST APIs using an API-First methodology. This blog posts gives some tips for doing so.