Specifying API Metadata

You can import or transform your API definition along with a metadata file that will allow you to configure certain processes in APIMatic as well as help override or filter out certain parts of the API definition without requiring any change in the input API specification itself.

What Can You Achieve With a Metadata File?

A metadata file provides the following capabilities:

Settings to help configure various processes an API definition goes through, in order to get desired results e.g. the metadata file provides settings that helps you configure transformation, import, export, merging, code generation etc.
Options to filter out parts of the API definition without needing to change the original API specification document e.g. you can remove internal endpoints of your API definition and related data.
Ability to override parts of the API definition with information provided in the APIMatic metadata file e.g. you can override the default authentication settings of your API.

How to Provide a Metadata File?

You can provide this file along with your API definition during import through APIMatic Dashboard or when converting APIs through the Transformer.
The metadata file must be a valid JSON file and the file name MUST start with "APIMATIC-META".
The API definition must be provided in the form of a ZIP file that contains both the API specification document (e.g. OpenAPI) and the metadata file. Within the ZIP file, the metadata file must exist at the same level as that of the API definition. It should not be nested at a different level.

Metadata - An Example

Here is an example directory structure where spec.json is the API specification document that needs to be imported/transformed. The metadata file named APIMATIC-META.json is placed at the same level as the API specification document and in the same directory.

  dir\
    spec.json
    APIMATIC-META.json

A sample of a metadata file APIMATIC-META.json is given below:

{
  "MergeConfiguration": {
    "MergeApis": false
  },
  "ImportSettings": {
    "PreferJsonSchemaNameOverTitle": true,
    "AppendParentNameForClashes": false,
    "AutoGenerateTestCases": true,
    "PreferSwaggerOperationSummaryOverId": false
  },
  "ExportSettings": {
    "ExportExtensions": false,
    "UseDateTimeOnlyInRaml": false,
    "AddRefSiblingDataInAllOfSchema": false,
    "EncodeUrlParamsInPostman": true
  },
  "ServerConfiguration": {
    "DefaultEnvironment": "production",
    "DefaultServer": "default",
    "Environments": [
      {
        "Name": "production",
        "Servers": [
          {
            "Name": "default",
            "Url": "http://example.com"
          }
        ]
      }
    ],
    "Parameters": []
  },
  "TestGenSettings": {
    "Configuration": {},
    "TestTimeout": 30,
    "PrecisionDelta": 0.01
  },
  "CodeGenSettings": {
    "SynchronyMode": "Asynchronous",
    "ModelSerializationScheme": "Json",
    "ArraySerialization": "Indexed",
    "Nullify404": true
  }
}

Configuring APIMatic Processes With Metadata

Using the APIMatic metadata file, you can configure the following processes in APIMatic in order to get the output that best suits your needs:

The API definition import process can be configured using import settings.
The API definition export process can be configured using export settings.
The API definition validation process can be configured using a validation configuration.
Merging of multiple API definitions can be enabled and configured using a merge configuration and related settings.
The API definition transformation process can be configured using a mix of the above mentioned settings as documented here.
The code generation process used for generating client SDKs from API definitions can be configured using Code Generation settings.
The test case generation process during code generation can be configured using the Test Case Generation settings.

Filtering Out Parts of API Definition With Metadata

The metadata offers the ability to filter out endpoints and their related data in an API definition on the basis of tags. Depending on the API specification format, tags can be specified for endpoints in different ways which is discussed in the next section. Filtering endpoints this way can be useful for removal of any private or internal endpoints that are part of your API specification document but you do not want to import.

During filtering, when endpoints are removed any redundant model definitions and authentication configurations tied only to those endpoints will also be removed. The two types of filtering options available are described below:

Property	Type	Details
KeepEndpointsWithTags	Array[String]	When this setting is used only the endpoints in an API definition that contain these tags will be kept while all others will be removed. If `RemoveEndpointsWithTags` is also used, then the removal of endpoints with tags specified in `RemoveEndpointsWithTags` takes place first while the filtering with current tags configuration applies later.
RemoveEndpointsWithTags	Array[String]	When this setting is used, all endpoints with the tags specified in this list are removed while others remain unaffected. If `KeepEndpointsWithTags` is also used, the endpoints with tags specified in the current tags configuration will be removed first and then the filtering on the basis of tags configuration in `KeepEndpointsWithTags` will take effect.
MaximumAllowedEndpoints	Integer	This will help remove any endpoints that fall above the maximum threshold specified using this setting. This type of filtering will be applied after any tags-specific filtering performed using `KeepEndpointsWithTags` or `RemoveEndpointsWithTags`.

Configuring Endpoint Level Tags In Your API Specification Document

Tags can be specified for OpenAPI and RAML files as shown below:

OpenAPI (v2.0, v3.x)

OpenAPI offers grouping operations (or endpoints) using tags natively using the tags property:

/pets:
  get:
    operationId: listPets
    tags:
      - pets

RAML (v1.0)

For RAML, we offer annotations to help specify tags at method level:

/pet:
  get:
    (x-tags):
      - pets
    displayName: List pets

Example Usage

Let's say you have two endpoints in your OpenAPI file. The first endpoint listPets has two tags pets and private specified while the second endpoint listCatalogItems has two tags pets and public specified:

/pets:
  get:
    operationId: listPets
    tags:
      - pets
      - private
    ..........

/pets/catalog/entries:
  get:
    operationId: listCatalogItems
    tags:
      - pets
      - public
    ..........

If you decide to keep endpoints with tag pets, upon API filtering both endpoints will be preserved since they both contain pets as their tag:

{
  "KeepEndpointsWithTags": ["pets"]
}

If you decide to remove the internal endpoints with tag private, upon API filtering only the first endpoint listPets and its related schema definitions will be removed while the information related to the second endpoint listCatalogItems will be preserved.

{
  "RemoveEndpointsWithTags": ["private"]
}

If you use both settings together as shown below, then endpoints with tag private and their related information will be removed first and remaining endpoints with tag pets will be preserved i.e. in the end you will be left with only one endpoint listCatalogItems.

{
  "KeepEndpointsWithTags": ["pets"],
  "RemoveEndpointsWithTags": ["private"]
}

Overriding Parts of API Definition With Metadata

note

This section is targetted for advanced use-cases only. We recommend that you talk to our technical support team before proceeding.

You can override the following parts of the API definition by specifying related objects in the Metadata:

API Description
Contact Details
Authentication Information
Server Configuration
Additional Headers

API Description

You can provide a description for your API in the APIMatic UI as described here. To define these details via the metadata file, you need to add a Description property as follows:

Example:

{
  "Description": "This is an API description. Add as many details as you like."
}

Contact Details Override

The contact details can be defined in the APIMatic UI as described here Contact Information. To define these details via the metadata file, you need to specify the Contact Object as follows:

Example:

{
  "Contact": {
    "Name": "John Doe",
    "Url": "https://www.example.com/contact/details",
    "Email": "john.doe@example.com"
  }
}

Contact Object

Name: Contact

The Contact Object has the following properties:

Property	Type	Details
Name	String	Name of person or organization.
Url	String	URL pointing to further contact information.
Email	String	Email of the person or organization.

Authentication Information Override

The details on the authentication options available in the APIMatic UI are described here and here. To enable these options via the metafile, you need to specify the Authentication Object as follows:

Example:

{
  "Authentication": {
    "Type": "Basic",    
    "Parameters": [
      {
        "Name": "username",
        "Description": "your username"
      },
      {
        "Name": "key",
        "Description": "your api key"
      }
    ]
  }
}

Authentication Object

Name: Authentication

The Authentication Object has the following properties:

Property	Type	Details
Type	Authentication Type	Specifies the type of authentication mechanism to apply. The value must be a valid string value from the list of values specified in this section.
Parameters	Array[Parameter Object]	The list of parameters that need to be sent as part of the authentication mechanism.
OAuth2AuthorizationServer	String	Name of server which serves as the base URL for the Authorization endpoint.
AuthorizationUrl	String	The route for the Authorization endpoint. This must be a relative URL.
OAuth2Server	String	Name of server which serves as the base URL for the Token endpoint.
AccessTokenUrl	String	The route for the Token endpoint. This must be a relative URL.
Scopes	Array[Scope Object]	List of scope definitions for OAuth v2.0 authentication mechanism.
OAuth2ClientIdExample	String	A value that can be used as an example or demo client ID for OAuth 2 auth types that support this parameter.
OAuth2ClientSecretExample	String	A value that can be used as an example or demo client secret for OAuth 2 auth types that support this parameter.
OAuth2UsernameExample	String	A value that can be used as an example or demo client username for OAuth 2 auth types that support this parameter.
OAuth2PasswordExample	String	A value that can be used as an example or demo client password for OAuth 2 auth types that support this parameter.

Authentication Type

Following are valid values for available authentication types in APIMatic:

Type	Details
None	No authentication mechanism will be applied.
Basic	Basic authentication flow will be applied.
OAuth_v2_BearerToken	OAuth v2.0 bearer token authentication mechanism will be applied.
OAuth_v2_WebServerFlow	OAuth v2.0 authorization code grant type will be used.
OAuth_v2_TwoLeggedFlow_ClientCredentials	OAuth v2.0 client credentials grant type will be used.
OAuth_v2_ImplicitGrantFlow_UserAgent	OAuth v2.0 implicit grant type will be used.
OAuth_v2_Resource_Owner_Password	OAuth v2.0 resource owner password grant type will be used.
OAuth_v2_Password_Only	A variant of OAuth v2.0 resource owner password grant type that does not require client id and client secret will be used.
CustomQuery	Authentication flow that uses custom parameters sent in the query will be used.
CustomHeader	Authentication flow that uses custom parameters sent in the header will be used.
CustomField	Authentication flow that uses custom parameters sent in as form parameters will be used.
JWT	JWT authentication mechanism will be applied.
CookieAuth	Cookie based authentication mechanism will be applied.

Parameter Object

Property	Type	Details
Name	String	Name of the authentication parameter.
Description	String	Details of the authentication parameter.
DefaultValue	String	Any default value for the authentication parameter.

Example:

{
  "Name": "apikey",
  "Description": "An API key is required for authentication"
}

Scope Object

Property	Type	Details
Name	String	A unique user-friendly name or ID for the scope.
Value	String	Actual value of the scope to be used during OAuth v2.0 authentication.
Description	String	A text describing what the scope does.

Example:

{
  "Name": "Read Notes",
  "Value": "read:notes"
}

Server Configuration Override

The details on the server configuration options available in the APIMatic UI are described here. To enable these options via the metafile, you need to specify the Server Configuration Object as follows:

Example:

{
    "ServerConfiguration": {
    "DefaultEnvironment": "production",
    "DefaultServer": "default",
    "Environments": [
      {
        "Name": "production",
        "Servers": [
          {
            "Name": "default",
            "Url": "https://example.com/production/{param}"
          }
        ]
      },
      {
        "Name": "sandbox",
        "Servers": [
          {
            "Name": "default",
            "Url": "https://example.com/sandbox/{param}"
          }
        ]
      }
    ],
    "Parameters": [
      {
        "Name": "param",
        "Type": "String"
      }
    ]
  }
}

Server Configuration Object

Name: ServerConfiguration

The Server Configuration Object has the following properties:

Property	Type	Details
DefaultEnvironment	String	This is the environment to be used by default across the API.
DefaultServer	String	This is the server to be used by default. This can be overridden at the endpoint level.
Environments	Array[Environment Object]	List of environments available in the API. An environment consists of a set of servers with base URL values.
Parameters	Array[Server Parameter Object]	List of path parameter definitions that can be referenced by server URLs in the server configuration environments.

Environment Object

The Environment Object has the following properties:

Property	Type	Details
Name	String	Name of the environment e.g. Production.
Description	String	Brief description of the environment.
Servers	Array[Server Object]	This lets you specify multiple servers within an environment. A server comprises of a name and a URL. The names of the hosts remain consistent over different environments but their values may vary.

Server Object

The Server Object has the following properties:

Property	Type	Details
Name	String	Name of the server.
Url	String	Base URL for the server.

Server Parameter Object

The Server Parameter Object has the following properties:

Property	Type	Details
Name	String	Name of the path parameter used in a server URL.
Description	String	This describes the path parameter.
Type	String	This is the name of the type assigned to the path/template parameter. A path parameter can be of the following types: String, Number, Number Enumeration, String Enumeration.

Additional Headers Override

The details on the additional headers available in the APIMatic UI are described here. To enable these options via the metafile, you need to specify the Additional Headers Object as follows:

Example:

{
  "AdditionalHeaders": [
    {
      "Name": "header",
      "Description": "This is a header description.",
      "DefaultValue": "default value for header"
    }
  ]
}

Additional Headers Object

Name: AdditionalHeaders

The Additional Headers Object has the following properties:

Property	Type	Details
Name	String	Name given to the header that has to be added with the API request.
Description	String	Brief description about the header.
DefaultValue	String	Value that has to be assigned to the header.

What Can You Achieve With a Metadata File?​

How to Provide a Metadata File?​

Metadata - An Example​

Configuring APIMatic Processes With Metadata​

Filtering Out Parts of API Definition With Metadata​

Configuring Endpoint Level Tags In Your API Specification Document​

OpenAPI (v2.0, v3.x)​

RAML (v1.0)​

Example Usage​

Overriding Parts of API Definition With Metadata​

API Description​

Contact Details Override​

Contact Object​

Authentication Information Override​

Authentication Object​

Authentication Type​

Parameter Object​

Scope Object​

Server Configuration Override​

Server Configuration Object​

Environment Object​

Server Object​

Server Parameter Object​

Additional Headers Override​

Additional Headers Object​

What Can You Achieve With a Metadata File?

How to Provide a Metadata File?

Metadata - An Example

Configuring APIMatic Processes With Metadata

Filtering Out Parts of API Definition With Metadata

Configuring Endpoint Level Tags In Your API Specification Document

OpenAPI (v2.0, v3.x)

RAML (v1.0)

Example Usage

Overriding Parts of API Definition With Metadata

API Description

Contact Details Override

Contact Object

Authentication Information Override

Authentication Object

Authentication Type

Parameter Object

Scope Object

Server Configuration Override

Server Configuration Object

Environment Object

Server Object

Server Parameter Object

Additional Headers Override

Additional Headers Object