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.
A sample of a metadata file
APIMATIC-META.json is given below:
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:
|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||Array[String]||When this setting is used, all endpoints with the tags specified in this list are removed while others remain unaffected. If |
|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 |
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
For RAML, we offer annotations to help specify tags at method level:
displayName: List pets
Let's say you have two endpoints in your OpenAPI file. The first endpoint
listPets has two tags
private specified while the second endpoint
listCatalogItems has two tags
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:
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.
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
Overriding Parts of API Definition With Metadata
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:
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:
"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:
"Name": "John Doe",
The Contact Object has the following properties:
|Name||String||Name of person or organization.|
|Url||String||URL pointing to further contact information.|
|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:
"Description": "your username"
"Description": "your api key"
The Authentication Object has the following properties:
|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.|
Following are valid values for available authentication types in APIMatic:
|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.|
|Name||String||Name of the authentication parameter.|
|Description||String||Details of the authentication parameter.|
|DefaultValue||String||Any default value for the authentication parameter.|
"Description": "An API key is required for authentication"
|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.|
"Name": "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:
Server Configuration Object
The Server Configuration Object has the following properties:
|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.|
The Environment Object has the following properties:
|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.|
The Server Object has the following properties:
|Name||String||Name of the server.|
|Url||String||Base URL for the server.|
Server Parameter Object
The Server Parameter Object has the following properties:
|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:
"Description": "This is a header description.",
"DefaultValue": "default value for header"
Additional Headers Object
The Additional Headers Object has the following properties:
|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.|