Create or Import an API Definition
Creating an API entity in the Dashboard requires a few simple steps after which you can easily perform one of the following: SDK generation, publishing a Developer Experience Portal, exporting the API entity into an API specification format of your choice, etc. There are two ways to add an API entity in the Dashboard:
- Create an empty API definition and later define its components using our API editor.
- If you have an API specification in one of the supported formats, it can be directly imported into APIMatic. You can easily configure the import process to get an output that meets your requirements.
Create API Definition
On the APIMatic Dashboard, click on Create and select Create New API to create an empty API entity.
Specify the new API Name, Base URI and Description. Click on Create API.
This will add the new API entity into your dashboard, and you get a prompt to edit the API. Clicking on Edit API redirects you to the APIMatic API Editor.
Import API Definition
Importing an API definition into Dashboard is recommended for the following scenarios:
- You are looking to generate an SDK or Developer Experience portal for your API specification document.
- You wish to edit your API specification document in our API editor before proceeding to use other features.
Importing is not recommended if you are looking to only convert between API specification formats as it uses a more stricter layer of validation for an optimal experience for users looking to generate an SDK or a Developer Experience portal. For converting between formats we recommend using our API Transformer which is more suited for this purpose.
You can easily import an API definition by following these steps:
On the APIMatic Dashboard, click on the Import option.
When importing, you can then either upload the API specification file from your local system or provide a URL that points to the API specification file.
Once the API specification is imported, it will be visible in the list of APIs in the Dashboard as shown below:
Supported Input Formats
The following API specification formats are supported and can be used as input during API definition import:
|API Specification Format||Version||File Format|
|WADL - W3C||2009||XML|
|WSDL - W3C||1.1||XML|
|I/O Docs - Mashery||-||JSON|
Importing an API Specification With Multiple Files
If your API specification document is split up into multiple files for reusability purposes or any other reasons, we recommend that you create a ZIP file and add all relevant files to it. Then, upload this ZIP file when importing. Ensure that all referenced files are part of the ZIP file and all relative paths to the files within the ZIP file are valid, to avoid any issues during import e.g. if you are uploading a RAML ZIP file, ensure that all files referenced using
$ref are all present in the uploaded ZIP file.
It is recommended that in a ZIP file, the main API specification file is present in the root directory. If that is not the case, the importer will iterate the ZIP file contents and pick the first file that validates as a main file in one of the supported input formats.
Importing Multiple API Specifications
If you wish to import multiple API specifications in order to create a single API entity out of them, then you need to enable merging in the root directory, ZIP all files and then import the ZIP file into APIMatic. It is very important to correctly structure the API specification documents when merging, to get desired results.
API definition import can be configured in two major ways:
Configuring via Metadata
You can import your API definition/specification along with the APIMatic's Metadata file that will allow you to configure the import process as per your requirements. The metadata file allows you to:
- Specify import-specific configuration settings.
- Filter the API definition before importing.
- Override certain API definition components before importing.
- Merge API specifications before importing.
The import configuration settings can be placed in an Import Settings Object in the root object of the Metadata file using the
ImportSettings property as shown below:
Import Settings Object
The available properties and their respective types are as follows:
Configuring via Format-Specific Vendor Extensions
APIMatic provides support for format-specific vendor extensions (e.g. for OpenAPI/Swagger, RAML and API Blueprint) so you can fine-tune your output and also configure our Code Generation engine from within your API specification file. For details, please refer to our detailed documentation on Extensions specific to your API definition file.
Does the API definition that I import into APIMatic become public?
No, an API imported into APIMatic is not available to the public. If you choose to export your API or generate a portal preview, your API definition is in a preview mode in which the URL of the page that opens is private and contains a GUID value in the path. Only people logged in with an APIMatic account can access the portal through that private URL.
Are .RAR and .7z files supported?
No, only .ZIP files are supported at the moment.
Is there a way to disable generation of test cases every time I import my API specification document?
Yes, you can easily configure the import process and achieve this by uploading a Metadata file with the
AutoGenerateTestCases import setting set to
I do not want to import internal endpoints from my API specification into APIMatic. Are there any filtering options available so only the public endpoints from my document can be imported?
You can easily configure the import process by uploading a Metadata file and achieve this by using the required filtering options as described here.
I often have the need to replace my imported API definition with a new API specification document version. Will I have to delete and then recreate an API entity each time?
No, you can simply replace your API definition with a new version, as described in the relevant section here.
I imported an API specification into the Dashboard successfully without any errors. However, when I opened the imported file in the API editor, I can see models named as ABC1, ABC2, ABC3, etc. I don't have models named this way in my specification document. Where did they come from?
Other than the models defined explicitly in the API definition by the user, we may create extra models in certain scenarios which are:
- Any enum values declared inline for parameters/responses/model fields are loaded as models and may appear that way in case of certain conversions.
- In certain cases where type information is not provided but an example is included we infer models from the example e.g. we automatically generate a model from the Request Body example given for any API Blueprint action request if its schema is not defined/indicated explicitly.
- If error responses use any models we load them separately as exception models internally.
- Any inline model declaration like the ones supported in RAML and OpenAPI are also loaded as explicit models.
In all of the above cases, the names of the models are generally derived from the component name (e.g. parameter name). Due to this, there is a chance that the derived model name may clash with other derived model names or with names of user defined models. We try to handle such clashes by appending a number at the end of the derived model so names like Model1, Model2, Model3, etc. may appear in the output.
If you are using inline models, we recommend that you either move such definitions to the global level and assign them a unique name or in case of OpenAPI use the property
title to assign unique names to the inline models. If inline models are not the root cause or it is not possible to modify the original specification document, we recommend that you configure the import process by enabling the import setting
AppendParentNameForClashes in a Metadata file. This setting will help assign the parent name to clashing model names instead of numbers and this can improve the output quality to some extent. Please see this section for more details.
It is not guaranteed for names auto-generated for inline schema definitions to remain unchanged when an API specification is updated. This can cause breaking changes in SDKs, resulting in potential compatibility issues. Therefore, it is recommended to avoid declaring schemas inline.
I have two OpenAPI API specifications in my ZIP folder. When I import the ZIP file, I only see endpoints from the first OpenAPI file while the second OpenAPI file seems to have gotten ignored. What can I do to import both my OpenAPI documents?
A typical import only supports importing a single API specification document at a time. In case of a ZIP file, the first main API specification file located in the ZIP folder is picked up and imported. If you wish to import multiple API specification documents you can either import them separately into the Dashboard or enable merging in the ZIP folder which will first merge the API specifications together and then import the merged API definition into the Dashboard.
I imported a WSDL file into APIMatic Dashboard and tried to make API calls through the generated portal but they were not successful. What am I doing wrong?
Our products do not support making SOAP requests. The WSDL support is aimed at facilitating migration of SOAP APIs to REST APIs in which any SOAP information is translated into a REST compatible information. The original SOAP structure is not preserved during import.
I'm getting the error "We could not identify the API definition format from the given file....". What am I doing wrong?
You may be seeing this error due to any of these common scenarios:
Your file was not in any of our supported input formats.
You tried uploading a Swagger/OpenAPI file without listing down the required swagger version. For
1.xSwagger files, you need to use the
swaggerVersionproperty, for version
swaggerproperty and for
openapi. Visit the respective specifications of these formats for more details.
You tried uploading a RAML fragment file e.g. a RAML library file. A RAML fragment file is not a valid API definition file. A RAML file must be a valid root document in accordance with RAML 0.8 root section or RAML 1.0 root section depending on the version you are using.
You tried uploading a valid RAML main file without specifying the RAML version. A RAML file must contain the required comment line indicating the version e.g. for RAML 0.8 the comment line should be
#%RAML 0.8whereas for RAML 1.0 it should be
You are trying to upload a Blueprint Markdown file but your file does not contain the required format and host information which helps our system distinguish your file from any normal Markdown file. Simply include these two lines at the start of your file and try importing again:
You can see Blueprint Metadata Section for more details.
You are trying to upload a JSON response data file or a JSON schema file or an XML data file which are not valid API definition files. Please ensure your file is in one of the supported formats. If however, you do not possess an API definition file, define an API entity on your Dashboard. You will need to provide details like API name, API definition, etc. for which you can learn more about in our documentation. Once the API entity is created, go to the Types section and import your JSON/XML file to load the models information.
You are trying to upload an XML schema file (XSD) which is not a valid API definition file. You can try embedding your XSD file into a WADL/WSDL file or upload a ZIP file that contains the WADL/WSDL file as well as any referenced XSD files. If however, you do not possess an API definition file, define an API entity on your Dashboard. You will need to provide details like API name, API definition, etc. for which you can learn more about in our documentation. Once the API entity is created, go to the Types section and import your XSD file to load the models information.
You tried uploading a WSDL/WADL file but faced this error. This could be due to invalid XML content. Please ensure that the content of your file validates against any XML validators and then try importing again. Also ensure that the root namespace of the file is valid. For WSDL, it should be
http://schemas.xmlsoap.org/wsdl/and for WADL it should be
Support for WADL 2006 format is limited. It is recommended to use the WADL 2009 format instead.
You tried uploading an API definition file that uses JSON format (e.g. OpenAPI, Swagger, Insomnia, Postman, Google Discovery, etc.) but faced this error. Please ensure that the content of the file contains valid JSON using any of the JSON validators available online and then try importing again.
The provided URL requires some kind of authentication and is not a publicly accessible link. Please ensure this is not the case and then try importing again.
You tried uploading a RAR/7Zip file which are not supported formats. Try importing again by using a ZIP file that contains a file in one of the supported formats.
I'm getting the error "Unable to resolve reference ..." / "Unable to load RAML Reference….". What should I do ?
The file you uploaded contains references using
!include that could not be resolved. The common causes for this are:
- The references involved external files that were not provided. In such a case, please upload a ZIP file that contains the main API definition file as well as any externally referenced files. Ensure that the relative paths provided in your API definition file are accurate with respect to the file structure in the ZIP file.
- The reference contains a URL that is not publicly accessible. Please provide a valid URL that works.
- The reference is internal (within the same file) but could not be resolved as the entity was not found e.g. if you get error for a reference like
"$ref": "#/definitions/DefinitionName"it means that a model definition with the name
DefinitionNamewas not defined under the root
definitionsproperty in your file. Provide this missing definition to avoid such errors.
Getting errors like "Reference to an undefined type found.". What should I do?
You can find documentation for this error here. Common causes of the error are:
It seems like you tried using a type for your parameter/model fields which was not a supported primitive type of that particular API definition format. In such a case, you need to explicitly define that particular type in the relevant section of the API definition file. For Swagger 1.x, such types must be defined under
modelsroot property, for Swagger 2.0 use
definitionsroot property, for OpenAPI 3.x use
schemasroot property in the Components section, for RAML 1.0 use
typesroot property while for RAML 0.8, Google Discovery, IO Docs Mashery use
API Blueprint does not complain if you use an undeclared type for a parameter or a request/response model. However, our tool requires you to declare these types under the Data Structures section if they are not primitive types supported by API Blueprint itself. A common mistake is using
$refin Swagger 1.x cannot refer to a primitive type. It must point to a Model's id so
"$ref": "string"is invalid since
stringis a primitive type. Use
Be sure to take care of the case of the name. A type may be declared with a different case compared to how it is being referenced. Ensure they are both same and then try again e.g. a type declared as
definitionNamecannot be referenced as
I'm getting the error "We do not support importing from an API documentation/reference. Please ensure your file is a raw API definition file and then try importing again". What should I do?
It looks like you tried importing by uploading an HTML file or provided a URL that referred to a web page which was possibly some form of API documentation. This is not supported as the URL/local file must point to a raw API definition file in the formats listed here and not its documentation/reference.
Note that we do have limited support for extracting API definition file from some of the API documentation pages e.g. if you have a URL to a public Apiary documentation of an API like
https://apimatic.docs.apiary.io/ we will be able to import using this. Additionally, some URLs from Swagger UI hosted documentation, MuleSoft Anypoint documentation and Postman docs may also be supported in some cases.
I'm getting the error "Error fetching API definition file from the URL provided....". What should I do?
Please ensure that the URL you provided is publicly accessible, does not require any kind of authentication and points to a raw API definition file in one of the supported formats listed here e.g. URLs like
localhost:XXXX will not work as they are only accessible on your system.
Getting the error for my RAML file "Unable to load external libraries. Please either upload a ZIP File containing all relevant files, or upload by URL." What does this mean?
Your main RAML file (or any fragment file) uses external libraries using the root
uses property and these could not be loaded. The common causes for this is:
The library file does not exist at the path provided. If you provided your files using a URL then it may be that the relative URL of the library file does not exist or is not accessible. Or you uploaded a single file or a ZIP file with missing files. Ensure that you upload a ZIP file in this case which contains all relevant files.
A RAML generally needs the
!includetag for referencing external files. However, for referencing external libraries the
!includetag must NOT be used.
I tried importing my OpenAPI file that at the moment only contains schema definitions and I was hoping to export them to the RAML format. However, I keep running into the error "No endpoint found for Code Generation.". Can I disable this error since I do not intend to perform any code generation?
Since your goal is only to convert between API specification formats, we recommend that you transform your API specification using our API Transformer instead of importing it into the Dashboard first. The import feature uses a more stricter layer of validation that is intended to give an optimal experience for users looking to generate an SDK or a Developer Experience portal.