Skip to main content

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

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:

PropertyTypeDetails
KeepEndpointsWithTagsArray[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.
RemoveEndpointsWithTagsArray[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.

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:

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:

PropertyTypeDetails
NameStringName of person or organization.
UrlStringURL pointing to further contact information.
EmailStringEmail 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:

PropertyTypeDetails
TypeAuthentication TypeSpecifies the type of authentication mechanism to apply. The value must be a valid string value from the list of values specified in this section.
ParametersArray[Parameter Object]The list of parameters that need to be sent as part of the authentication mechanism.
OAuth2AuthorizationServerStringName of server which serves as the base URL for the Authorization endpoint.
AuthorizationUrlStringThe route for the Authorization endpoint. This must be a relative URL.
OAuth2ServerStringName of server which serves as the base URL for the Token endpoint.
AccessTokenUrlStringThe route for the Token endpoint. This must be a relative URL.
ScopesArray[Scope Object]List of scope definitions for OAuth v2.0 authentication mechanism.
OAuth2ClientIdExampleStringA value that can be used as an example or demo client ID for OAuth 2 auth types that support this parameter.
OAuth2ClientSecretExampleStringA value that can be used as an example or demo client secret for OAuth 2 auth types that support this parameter.
OAuth2UsernameExampleStringA value that can be used as an example or demo client username for OAuth 2 auth types that support this parameter.
OAuth2PasswordExampleStringA 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:

TypeDetails
NoneNo authentication mechanism will be applied.
BasicBasic authentication flow will be applied.
OAuth_v2_BearerTokenOAuth v2.0 bearer token authentication mechanism will be applied.
OAuth_v2_WebServerFlowOAuth v2.0 authorization code grant type will be used.
OAuth_v2_TwoLeggedFlow_ClientCredentialsOAuth v2.0 client credentials grant type will be used.
OAuth_v2_ImplicitGrantFlow_UserAgentOAuth v2.0 implicit grant type will be used.
OAuth_v2_Resource_Owner_PasswordOAuth v2.0 resource owner password grant type will be used.
OAuth_v2_Password_OnlyA variant of OAuth v2.0 resource owner password grant type that does not require client id and client secret will be used.
CustomQueryAuthentication flow that uses custom parameters sent in the query will be used.
CustomHeaderAuthentication flow that uses custom parameters sent in the header will be used.
CustomFieldAuthentication flow that uses custom parameters sent in as form parameters will be used.
JWTJWT authentication mechanism will be applied.
CookieAuthCookie based authentication mechanism will be applied.

Parameter Object

PropertyTypeDetails
NameStringName of the authentication parameter.
DescriptionStringDetails of the authentication parameter.
DefaultValueStringAny default value for the authentication parameter.

Example:

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

Scope Object

PropertyTypeDetails
NameStringA unique user-friendly name or ID for the scope.
ValueStringActual value of the scope to be used during OAuth v2.0 authentication.
DescriptionStringA 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:

PropertyTypeDetails
DefaultEnvironmentStringThis is the environment to be used by default across the API.
DefaultServerStringThis is the server to be used by default. This can be overridden at the endpoint level.
EnvironmentsArray[Environment Object]List of environments available in the API. An environment consists of a set of servers with base URL values.
ParametersArray[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:

PropertyTypeDetails
NameStringName of the environment e.g. Production.
DescriptionStringBrief description of the environment.
ServersArray[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:

PropertyTypeDetails
NameStringName of the server.
UrlStringBase URL for the server.

Server Parameter Object

The Server Parameter Object has the following properties:

PropertyTypeDetails
NameStringName of the path parameter used in a server URL.
DescriptionStringThis describes the path parameter.
TypeStringThis 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:

PropertyTypeDetails
NameStringName given to the header that has to be added with the API request.
DescriptionStringBrief description about the header.
DefaultValueStringValue that has to be assigned to the header.