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. For example, 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. For example, 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. For example, 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 (for example, 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 shouldn't 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. Additionally, you can filter individual schema properties and parameters within your API specification. Depending on the API specification format, tags can be specified for endpoints, properties, and parameters in different ways, which is discussed in the sections below. Filtering this way can be useful for removal of any private or internal elements that are part of your API specification document but you don't 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 filtering options available are described below:

Endpoint Level Filtering

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.

Property and Parameter Level Filtering

Property	Type	Details
RemoveSchemaPropertiesWithTags	Array[String]	When this setting is used, all schema properties with the tags specified in this list are removed from the API definition. If removing properties leaves behind orphaned schemas, those schemas are automatically removed as well. By default, examples are also updated to remove references to the filtered properties across endpoint-level examples, custom type examples, and child schemas that inherit from filtered parent schemas.
RemoveParametersWithTags	Array[String]	When this setting is used, all parameters (path, query, header, and so on) with the tags specified in this list are removed from the API definition. If removing parameters leaves behind orphaned schemas, those schemas are automatically removed as well.

caution

Use the RemoveSchemaPropertiesWithTags setting with caution as it involves significant risks. This feature removes properties at the schema level throughout your API specification and can have wide-ranging effects, including impacts to generated SDKs, documentation, schema validation, schema relationships, examples, and API contracts.

View Associated Risks and Impacts

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

Configuring Property and Parameter Level Tags In Your API Specification Document

For more granular filtering, you can tag individual properties within schemas and parameters using the x-tags extension field.

Tagging Schema Properties

Use the x-tags field to associate tags with properties in your schema definitions:

DeviceInfo:
  type: object
  properties:
    id:
      type: string
      x-tags: ["schema1"]
    name:
      type: string
      x-tags: ["beta", "internal"]
    status:
      type: string

Tagging Parameters

Similarly, add x-tags to parameters at the endpoint level:

parameters:
  - name: deviceId
    in: path
    required: true
    schema:
      type: string
    x-tags: ["schema1"]
    example: "device-123"
  - name: apiVersion
    in: query
    required: false
    schema:
      type: string
    x-tags: ["beta"]
    example: "v2"

Example Usage

Endpoint Level Filtering

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, endpoints with the tag private and their related information will be removed first, and the remaining endpoints with the tag pets will be preserved. In the end, you'll be left with only one endpoint: listCatalogItems.

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

Property and Parameter Level Filtering

Let's say you have a schema definition with tagged properties:

DeviceInfo:
  type: object
  properties:
    id:
      type: string
      x-tags: ["public"]
    name:
      type: string
      x-tags: ["beta"]
    internalId:
      type: string
      x-tags: ["internal"]
    status:
      type: string

And an endpoint with tagged parameters:

/devices/{deviceId}:
  get:
    parameters:
      - name: deviceId
        in: path
        required: true
        schema:
          type: string
        x-tags: ["public"]
      - name: debugMode
        in: query
        schema:
          type: boolean
        x-tags: ["internal"]

If you want to remove all internal and beta properties/parameters from your API definition:

{
  "RemoveSchemaPropertiesWithTags": ["beta", "internal"],
  "RemoveParametersWithTags": ["internal"]
}

After filtering:

• The name and internalId properties will be removed from the DeviceInfo schema
• The debugMode parameter will be removed from the endpoint
• Only the id and status properties will remain in DeviceInfo
• Only the deviceId parameter will remain in the endpoint
• All examples referencing the removed properties (name and internalId) will be automatically cleaned up

Combining Endpoint and Property Level Filtering

You can use both endpoint-level and property-level filtering together by specifying each setting individually:

{
  "RemoveEndpointsWithTags": ["internal"],
  "RemoveSchemaPropertiesWithTags": ["beta"],
  "RemoveParametersWithTags": ["deprecated"]
}

Alternatively, you can use the RemoveInformationWithTags property to combine all three filtering levels with a single setting:

{
  "RemoveInformationWithTags": ["internal", "beta", "deprecated"]
}

When using RemoveInformationWithTags, the specified tags will be applied across all filtering levels simultaneously:

1. Remove all endpoints tagged with the specified tags
2. Remove all schema properties tagged with the specified tags and update all related examples
3. Remove all parameters tagged with the specified tags
4. Clean up orphaned schemas that are no longer referenced

Example:

If you use:

{
  "RemoveInformationWithTags": ["internal"]
}

This is equivalent to:

{
  "RemoveEndpointsWithTags": ["internal"],
  "RemoveSchemaPropertiesWithTags": ["internal"],
  "RemoveParametersWithTags": ["internal"]
}

All endpoints, schema properties, and parameters tagged with internal will be removed from your API definition in a single operation.

Associated Risks and Impacts

When using the RemoveSchemaPropertiesWithTags feature, the following risks and impacts should be considered:

• Example descriptions/summaries may still reference removed properties, creating misleading documentation where text doesn't match actual content
• minProperties/maxProperties constraints may become impossible to satisfy after property removal
• Removed properties will be treated as unvalidated additional properties if additionalProperties: true is set
• When example cleanup is disabled through the import setting RemoveUndeclaredPropertiesFromExample , removed properties appear as additional properties in the portal and generated code samples.
• Removing a discriminator property breaks the entire polymorphic schema structure
• Property removal from parent schemas propagates to all child schemas inheriting via allOf
• Removing distinguishing properties can make oneOf/anyOf schemas identical, causing validation ambiguity
• Default values assigned to removed properties are lost, potentially changing API behavior
• Callback payload structures change when they reference schemas with removed properties
• Links with runtime expressions break when they reference removed properties

Overriding Parts of API Definition With Metadata

note

This section is intended 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 doesn't 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",
        "DefaultValue":"Default Value for Param"
      }
    ]
  }
}

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 (for example, 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.
DefaultValue	String	Value that has to be assigned to Parameter

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.