While importing API specs isn’t difficult, it’s also not uncommon to hit a bump in the road during the process. Understanding just a few key principles will ensure the import process goes smoothly.

The components of modern RESTful APIs can be defined using the widely-adopted OpenAPI specification (OAS). OAS makes it easy to share existing API definitions – resource descriptions, authentication methods, and even metadata, like licensing – with other applications and services.

Assertible extends the value of your OpenAPI spec by providing tools to automatically import, test, and sync your spec file. When importing a new web service from an OpenAPI/Swagger specification, Assertible automatically generates a test for each endpoint/method in your API, and adds assertions for status code and JSON responses.

Simple tips for successfully importing your API

If your import doesn’t work on the first try, don’t worry, this post will help you import your spec successfully. Maybe you got an error message, or maybe the import just didn’t do what you expected. Either way, the good news is that most fixes are quick and easy.

Success starts with getting the following basics right:

1. Locating the specification file Locate the correct specifications file and its URL or file path.
2. Importing the specification file Select the import option that matches your spec file. Postman collection specs below v2 will need to be updated before import.
3. Resolving common errors Understanding how to address the most common errors will speed up resolution.

Let’s take a closer look at each item...

Locating the specification file

The API spec is just a text file in either JSON or YAML format (with a .json or .yaml extension). There are two main ways to locate the OpenAPI/Swagger specification file:

• Via Swagger UI: If you use Swagger UI, you can get the full link to the specification file from that page. For example: https://petstore.swagger.io/.
• Via Swagger Editor: You can export the API spec by selecting either Save as YAML or Convert and save as JSON from the File menu.

From the Swagger editor you can export the API spec by selecting either Save as YAML or Convert and save as JSON from the File menu.

NOTE If you’re using Postman, you can export a collection from the Collections menu in the Postman UI. Be sure to select v2 or higher from the export dialog.

Importing the specification file

Once you’ve identified the location of the spec file, you can import it from either a URL or a local file. Importing the spec is the first step in creating a web service from your dashboard.

Assertible's user guide offers detailed instructions for importing an OpenAPI/Swagger spec v2 or v3 or a Postman collection v2 or higher.

What happens when you click Import spec

After following those instructions and clicking the Import spec button, the system should initialize the new web service, and generate an automated test for each method/endpoint defined in the spec.

But What if you get an error instead? Let's look at some quick fixes to errors like the one shown below.

Resolving common errors

Import errors are typically the result of either an incorrect file path, or the file contents not matching the expected format.

The text of the error message may suggest a next step, but here are some additional notes to accelerate resolution for each type of error...

ERROR: "File is not a valid Swagger spec…"

What happened?: The most common reason for this error is entering the base URL of the API in the URL field, rather than the URL or path to the actual spec file.

Tips for resolution:

1. Confirm that the URL/path you entered is correct, and that it points to a valid .json or .yaml file.
2. Confirm that your choice of spec in the UI matches the spec of the file you're trying to import. OpenAPI/Swagger file formats differ from Postman collections.
3. Try using the transformation tools at APIMatic to open the file and transform it to a v2 or v3 version of the OpenAPI spec. If APIMatic can't open it, you probably don't have the right file.

ERROR: “Failure to parse...”

What happened?: Although the system found the file specified, the contents could not be validated. This error might indicate invalid syntax in the spec, an unsupported version, file corruption, or that the file contains a pre-v2 collections or OAS spec.

Tips for resolution:

1. Confirm that the file specified is a valid OpenAPI/Swagger(v2 or v3) or Postman collections (v2 or higher) specification.
2. Try exporting your collection from Postman again, making sure to select v2 or higher from the export dialog.
3. Use the APIMatic tools to transform the file into a supported version.

ERROR: “Postman Collection v1 not supported. Assertible only supports Postman Collection v2 and higher. To fix this problem, import your collection into Postman then export it as v2.”

What happened?: Note that this error suggests your file is a valid Postman collection, but that your spec predates collections v2. Assertible supports only v2 and above.

Tips for resolution:

1. Use APIMatic to transform the file into a supported version.
2. Use Postman to export the collection as v2 or higher. Even if you don't have Postman, it is free to download or use online. It’s easy to install, and with just a few clicks you can import and export collections from the file menu. Import the file into Postman, then export it from the Collections menu, making sure to select v2 or higher from the export dialog.

ERROR: “Cannot fulfill request, exceeded limit for your web services...”

What happened?: Your file may be perfectly valid, but the system didn't actually import it. Instead, the error indicates you have exceeded the maximum number of web services allowed under your current plan.

Tips for resolution: You can either upgrade your account to increase the limit or delete an existing web service to make room for the new one.

1. To upgrade, go to your billing settings and select a new plan.

2. To delete an existing web service, click the Manage service link to the right of the Web service entry on the Dashboard page. Select Manage from the Settings menu on the left, then select Delete.

NOTE Deleting a web service cannot be undone. Be sure to delete only services that you no longer need.

Once you've corrected the issue, repeat the import process in Assertible, on the New service page.

Getting assistance

If you’re still having trouble, we’re here to help. Please contact us and we’ll have an Assertible expert guide you through the import process.