Tips on using Stoplight for API Design for API Builder

Note: Since this post was first published, there have been many changes with both products. Please refer to this blog post that highlights updated tips and supersedes the following blog post.

Axway’s API Builder makes it easy to create APIs in minutes with a low-code/no-code interface and a powerful flow engine.

A common starting point for creating APIs is an API description in the form of an OpenAPI specification. Stoplight is a powerful API Design tool for creating OpenAPI specifications.

This post will describe a couple of tips for using Stoplight to create API definitions for API Builder.

OpenAPI 3.0 vs OpenAPI 2.0

You can read about the differences between OpenAPI 2.0 (OAS2) and OpenAPI 3.0 (OAS3) here but the main point of bringing this up is that while Stoplight supports both, it defaults to OAS3.

Furthermore, while API Builder support for OAS3 is currently in the works, it currently only supports OAS2.

Until API Builder supports OAS3, when you create your Stoplight API definition, you should select OAS2 as shown below:

Note that you can select either JSON or YAML as the format for the API

Remove References

When you design your API in Stoplight, you should be using models and references to models for your endpoint body and response definitions as shown below:

In the screenshot above, you can see that my Get all employees endpoint returns an array of employees defined as a reference to the employee model as follows:

array[$ref(../models/employee.v1.yaml)]

This makes maintaining your API project(s) and collaboration more scalable.

However, when you export your API so that it can be imported into API Builder, you need to dereference these as shown below:

Note that you can select either JSON or YAML as the format for the API since API Builder supports both on import.

If you don’t dereference your references (i.e. select Bundled), you will get an error when trying to import the API definition file into API Builder as shown below:

Summary

In this blog post, we looked at two tips for using Stoplight for creating API definitions for use with API Builder, namely (a) to use OAS2 when creating your API in Stoplight and (b) select dereferenced for your references on the export of your API in Stoplight.