Why You Should Create an API Definition and How To Do It

So you’ve set out to build an awesome API... great! Or you already have an API... even better!

Creating a definition for your API is an important step in API development that is often overlooked. API definitions (sometimes referred to as API specifications or description formats) are designed to provide a format for describing APIs that is readable by machines. They are language-agnostic, so you can benefit from them no matter what language you choose. 

Today, the most commonly used definition for APIs is the OpenAPI Specification. The OpenAPI Specification (OAS), which is based on the original Swagger Specification, defines RESTful standards for APIs. OAS Definitions map resources and operations for an API.

This article describes some of the the benefits of creating a definition, and some tools you can use to make your life easier.

Why Create a Definition

Your API definition can be used to:

• Help internal folks understand the API and agree on its attributes: This was powerful for my last company. An API definition allows documentation tools like Swagger UI to visualize APIs. We used Swagger UI to visualize all of our internal APIs so that developers could use upstream and downstream services quickly and easily. SwaggerHub has team and enterprise-level features to design, view, and collaborate on APIs.
• Help external folks understand the API and what it can do: Again, Swagger UI is a well-used visualization tool for documentation, my personal favorite being the Marvel API. There are other cool documentation solutions that take API definition files as their input, such as ReDoc, ReadMe, and Slate.
• Create tests for your API: Your OAS definition provides a contract that describes what responses look like when someone calls your API. This contract can be re-purposed to create test cases. That can drastically decrease the amount of setup team needed to test your APIs. You can create functional tests, load tests, run security scans, AND virtualize your APIs from your API definition using ReadyAPI, and you can kick it all off by importing your API Definition
• Generate implementation code and SDKs: In addition to generating documentation, OpenAPI definitions can be used to accelerate development by creating implementation code and SDKs. API Definition files can be imported into a number of different tools like Swagger Codegen and SwaggerHub. They can create code in many different languages, like Java, Scala, and Ruby. Create implementation code so that you don’t have to write your API code from scratch.
• Make your API live: API gateways like Amazon API Gateway, Azure, Apigee, or Google Cloud, all take API definitions to create a live API.
• Monitor your API: Ideally, you want to know if your API has issues BEFORE your customers notice. If you import your definition into a tool like Alertsite, the API can be monitored automatically.

Your API definition should serve as the source of truth for your API. It can be used to implement the API, document the API, and power tools you need to make sure your API is successful.

Creating an API Definition

Now that I’ve described why you might create a definition, I’ll describe some approaches on how to do so. You have a few options:

1. Design your API first, and optionally create implementation code from the definition
2. Make calls to your API and use those requests to create the definition
3. Have your code generate the definition

1. Write the definition first (then implement)

The “Design First” approach advocates for writing your API definition first before writing any code. This is a relatively new approach, but is catching on quickly. Spotting design issues before writing any code is more efficient than catching issues after the implementation is done.

Team-based tools, like SwaggerHub, offer great features to design and collaborate on APIs. You can set admin-level permissions, give users the ability to make and merge changes to the definition, and you get a visual editor. You could also read up on how to create an OpenAPI-compliant definition and use a text editor to create a YAML file. If you want additional tools, and don’t want to use SwaggerHub, you can use Swagger-Editor to edit, Swagger-UI to document, and Swagger-Validator to validate your definition.

Once you’ve created your definition, you can create implementation code for your API. SwaggerHub makes it easy to create implementation code (server stubs). You can also use this open source library, Swagger-Core to do the same. You’ll need to add any business logic that can’t be described by the definition alone. You can set up your processes to create implementation code whenever your API definition changes. 

2. Use Swagger Inspector to create the definition from API calls

If you already have your API implemented (at least partially), you can simply make requests to your API from Swagger Inspector.

Swagger Inspector can execute API requests, validate responses, and create OpenAPI definitions. You can create documentation for existing APIs by calling endpoints, selecting them, and clicking CREATE API DEFINITION.

This automatically generates the OpenAPI file for endpoints you select, saving valuable development time. We store the definition in SwaggerHub for free, and you have immediate access to the documentation for your API. You can also export the file and create client SDKs.

This method leads to a snapshot of an API, but if your API doesn’t change that much, it doesn’t matter! This is probably the fastest method of creating an API Definition, and my favorite, because it uses our new product, Swagger Inspector. Be sure to leave feedback in the bottom-right widget if you have suggestions!

3. Code-generated definitions

There are several projects that can help you generate your API Definition from code. The one we’ve spent the most time on here at SmartBear is Swagger-Core, which can be used with Java 7 or 8 and maven 3.0.4+. SmartBear also contributes to Scala and Javascript projects that create definitions based on your code. If you use a different language, chances are you can find a library with a little searching. For instance, SwashBuckle is a .NET library that can do the same thing.

Creating a definition from your code is an excellent way to go. It ensures that your definition is consistent with your implementation. This comes with some challenges. For example, you need to make sure the definition has human-friendly descriptions and examples. If you have a dedicated tech writer, they should collaborate closely with your developers to make this approach work well.

Whichever option you choose to use, we hope these tips help you create a great API!