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

1. On the APIMatic Dashboard, click on Create and select Create New API to create an empty API entity.

   

2. Specify the new API Name, Base URI and Description. Click on Create API.

   

3. 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:

1. On the APIMatic Dashboard, click on the Import option.

   

2. 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.

   

3. 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
OpenAPI/Swagger	3.1 3.0 2.0 1.x	JSON/YAML JSON/YAML JSON/YAML JSON
RAML	1.0 0.8	YAML YAML
Postman Collection	2.0 1.0	JSON JSON
Insomnia	3	JSON/YAML
HAR	1.2	JSON
API Blueprint	1A	Markdown
WADL - W3C	2009	XML
WSDL - W3C	1.1	XML
Google Discovery	-	JSON
I/O Docs - Mashery	-	JSON
APIMATIC	-	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 !include or $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.

Configuring Import

API definition import can be configured in two major ways:

1. Via the APIMatic Metadata file.
2. Via Format-Specific Vendor Extensions

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.

Import Settings

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:

{
    "ImportSettings": {
        "PreferJsonSchemaNameOverTitle": true,
        "AppendParentNameForClashes": true,
        "AllowModelTypesWithNoFields": true
    }
}

Import Settings Object

The available properties and their respective types are as follows:

Setting	Type	Purpose
ExampleResolvingMaxDepth	Integer	Default: 1. The maximum depth for importing models from nested schemas present within examples. If you are facing performance issues, consider setting this to a lower value.
PreferJsonSchemaNameOverTitle	Boolean	Default: false. If a title is specified in a JSON Schema definition we consider that as the model name. However, when this flag is set as true, we give precedence to the definition name instead of the one specified using property title.
AppendParentNameForClashes	Boolean	Default: false. When loading models/complex types, if there is a clash in names we append a number with the name of the clashing type. When this flag is set as true, the name of the parent component is appended with the name instead.
IgnoreRamlTypeDeclarationDisplayName	Boolean	Default: false. When set to true, the displayName property for any RAML v.1.0 Type Declaration Object will be ignored and the key name specified at the time of declaring this object will be preferred instead.
PreferSwaggerOperationSummaryOverId	Boolean	Default: false. When set to true, we will give more precedence to OpenAPI/Swagger Operation Object's summary instead of operationId during endpoint name extraction.
AutoGenerateTestCases	Boolean	Default: true. For several formats like OpenAPI (v3.x), API Blueprint, RAML, Postman and HAR, we support auto-generating test cases from request/response examples (if any are present). This can be disabled by setting this flag to false.
AllowModelTypesWithNoFields	Boolean	Default: false. When set to true, model definitions containing no properties/fields will also be imported.
IgnoreInlineEnumModelDescription	Boolean	Default: false. When set to true, ignores any description defined inline for an enum schema.
ImportMultipleResponses	Boolean	Default: true. When set to false, any data related to multiple responses including additional types created for these responses will be removed.
LoadOneOfAsOptionalFields	Boolean	Default: false. When set to true, oneOf schemas will be combined and imported as a single model with all fields considered as optional.
ImportArrayOfMapsAndMapOfArrays	Boolean	Default: false. Schemas containing arrays of maps or maps of arrays will be treated as dynamic types during import, by default. When this flag is set to true, however, such schema definitions will be imported and the type set accordingly.
ImportTypeCombinators	Boolean	Default: true. Type combining constructs like union types, anyOf, oneOf and not will be imported by default. Any extra types associated with these constructs will also be loaded. To disable this, set the flag value to false.
UseRamlUnionTypeAsOneOf	Boolean	Default: true. RAML v1.0 union types are loaded as the equivalent of oneOf type construct by default. When set to false, the union types are loaded as an equivalent of the anyOf type construct.
ImportWsdlWithJsonMediaTypes	Boolean	Default: false. When set to true, all application/xml request/response media types will be treated as application/json during WSDL import. XML metadata (including details about XML node name, namespace, prefix etc.) will also not be imported.
EnableCookieAuthentication	Boolean	Default: false. When set to true, allows the import of cookie authentication schemes.
AllowAuthForEmptySecurityObject	Boolean	Default: false. When set to true, allows authentication to be enabled even when the operation level security object is empty.
ImportFromOpenApiDiscriminatorMapping	Boolean	Default: true. When set to false, information from the mapping property in the OpenAPI v3 Discriminator object is not imported.
ImportRequestBodyContentTypeHeader	Boolean	Default: true. When set to false, request's content type information will not be imported as explicit Content-Type header.
ImportMultipleAuthentication	Boolean	Default: true. All authentication schemes available in the API are loaded as is, by default. When set to false, however, only the first authentication scheme from the API will be imported.
ImportOpenApi3EmptySchema	Boolean	Default: true. Empty schema declarations will not be ignored by default. If set to false an empty schema will be treated as if no schema was declared.
LoadBaseTypesForOneOfAnyOfDiscriminator	Boolean	Default: false. By default, no additional base types will be created and exporting to formats where discriminator is not supported alongside oneOf/anyOf may see loss of information related to it. When set to true, additional base types will be created for cases where discriminator information is present alongside oneOf or anyOf.
ImportTypeCombinatorsWithOnlyOneType	Boolean	Default: true. By default, type combinators (e.g. anyOf, oneOf, not) containing only one type definition in their list will be imported as is. When set to false, the type combinators lists will not be populated. Instead, the single type definition will be extracted from the list and considered as the default type of the component.
AppendParentSchemaNameToOneOfAnyOfBaseType	Boolean	Default: false. Base types auto-generated from cases involving oneOf/anyOf discriminators will have default names. When set to true, the name of the parent schema may be appended with the default name, if applicable. This is recommended for cases where multiple oneOf/anyOf schemas are expected to have the same discriminator property name.
IgnoreEndpointSummary	Boolean	Default: false. By default, an endpoint's summary will not be assigned to the endpoint's description if it is missing. When set to true, the summary is set as the endpoint's description in the scenario where the description has not been explicitly defined.
PreserveSingleValueEnum	Boolean	Default: false. By default, an enum containing only a single value will be converted to a constant for OpenAPI 3.0. When set to true, the enum is not converted to a constant i.e. remains an enum.
UseStrictValidation	Boolean	Default: false. The default validation is flexible and may disregard some issues in the spec to make it easier for users to import their specs. When set to true, all mandatory/recommended validation and lint checks will be enforced.
ImportAdditionalHeader	Boolean	Default: true. By default, an additional header is imported when multiple authentication schemes have been defined. When set to false, this additional header is not imported.
ImportAdditionalErrorModels	Boolean	Default: true. When set to false, any additional error models generated for multiple error responses upon import are removed.
ImportAdditionalCustomTypeAdditionalFields	Boolean	Default: true. When set to false, additionalProperties defined within a schema are not imported.
AllowAdditionalEnumItems	Boolean	Default: false. When set to true, allows all enumeration schemas to accept any unknown properties defined.
ImportAdditionalTypeCombinatorModels	Boolean	Default: true. When set to false, prevents importing additional unused models associated with type combinators.

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.

Import FAQs

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 false.

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.

Import Troubleshooting

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:

1. Any enum values declared inline for parameters/responses/model fields are loaded as models and may appear that way in case of certain conversions.
2. 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.
3. If error responses use any models we load them separately as exception models internally.
4. 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.

danger

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.x Swagger files, you need to use the swaggerVersion property, for version 2.0 use the swagger property and for 3.x use 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.8 whereas for RAML 1.0 it should be #%RAML 1.0.

• 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:

  FORMAT: 1A
  HOST: http://hostname.com

  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 http://wadl.dev.java.net/2009/02.

  note

  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 $ref or !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 DefinitionName was not defined under the root definitions property 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 models root property, for Swagger 2.0 use definitions root property, for OpenAPI 3.x use schemas root property in the Components section, for RAML 1.0 use types root property while for RAML 0.8, Google Discovery, IO Docs Mashery use schemas root property.

• 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 bool instead of boolean.

• $ref in Swagger 1.x cannot refer to a primitive type. It must point to a Model's id so "$ref": "string" is invalid since string is a primitive type. Use type instead.

• 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 definitionName cannot be referenced as DefinitionName.

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 !include tag for referencing external files. However, for referencing external libraries the !include tag 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.