SHARE THIS ARTICLE

Metadata

You can now import/convert your API description along with a metadata file that will allow you to configure Code Generation Settings for your API, override authentication settings or control parsing of some components. Details on how to provide this file and its format are provided below.

Applicability

You can provide this file along with your API description during import on the My APIs page or when converting APIs on the Transformer.

Metadata File

The metadata file must be a valid JSON file and the file name MUST start with “APIMATIC-META”.

How to Provide the Metadata File

The API description must be provided in the form of a ZIP file that contains both the API description and this metadata file. Within the ZIP file, the metadata file must exist at the same level as that of the API description. It should not be nested at a different level.

Advantages

  1. When importing an API through the My APIs page, this file enables you to configure Code Generation settings for your API. This is useful when you are importing from a format other than APIMATIC that do not have support for specifying additional parameters useful only to SDK generation in APIMATIC.

  2. You can override the default authentication settings of your API with those specified in the file.

  3. Helps you import various components of an API description file in accordance with any rules specified in the settings.

File Format

The metafile can consist of various JSON objects that will help specify this information. These objects are described in the sections below.

Authentication

The details on the authentication options available in APIMATIC are described here API Authentication. To enable these options via the metafile, you need to specify the authentication object that has the following properties:

Authentication Object

Name: Authentication

PropertyTypeDetails
TypeStringMUST be a value from one of [None,Basic, OAuth_v2_BearerToken, CustomQuery,CustomHeader, OAuth_v1_TokenSecret, CustomAuth, JWT, OAuth_v1_Cert_PKCS12_RSA, OAuth_v1a_OneLeggedFlow]
Parameters[Parameter Object]Array of type Parameter Object

Example:

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

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"
  }

Code Generation Settings

The details on the available code generation settings is available at Code Generation Settings . These can be specified in the form of an object as described below:

Code Generation Object

Name : CodeGenSettings

The available properties and their respective types are as follows:

SettingTypePurpose
SynchronyModeNumber. Could be 0 or 1.0 represents Asynchronous while 1 represents Synchronous. When Asynchronous, the CodeGen engine generates asynchronous C# and Java code.
UseHttpMethodPrefixBooleanWhen true, HTTP verbs are used as prefix for generated controller methods.
UseModelPrefixBooleanWhen true, a postfix “Model” is appended to all classes generated from schemas.
UseEnumPrefixBooleanWhen true, a postfix “Enum” is appended to all enumerations lifted from “allowedValues”.
AppendContentHeadersBooleanWhen true, code generation engine automatically detects request and response schema and appends content headers e.g., “accept: application/json” and “content-type: application/json” headers for JSON serialization mode.
UseCommonSDKLibraryBooleanWhen true, a common library comprising of common classes is used by the generated SDKs
UseControllerPrefixBooleanWhen true, a postfix “Controller” is appended to all controllers generated from path groups.
GenerateInterfacesBooleanWhen true, interfaces for controller classes are generated in the generated SDKs
PreserveParameterOrderBooleanWhen true, parameter order is tried to be preserved in endpoints and models
AndroidUseAppManifestBooleanWhen true, configuration values e.g., authentication credentials, are expected in AndroidManifest.xml file for the Android SDK. When set, this setting ignores useConstructorsForConfig flag.
EnablePHPComposerVersionStringBooleanWhen true, adds version component to composer.json file in PHP SDKs. This can cause conflicts with Git tag-based version publishing and should be used with care.
iOSUseAppInfoPlistBooleanWhen true, configuration values e.g., authentication credentials, are expected in app-info.plist file for the iOS SDK. When set, this setting ignores useConstructorsForConfig flag.
iOSGenerateCoreDataBooleanWhen true, iOS CoreData schema and classes are generated.
CollapseParamsToArrayBooleanWhen true, collapse more than 3 parameters into an options arrays
Nullify404BooleanWhen true, null response will be returned on the HTTP status code 404
ValidateRequiredParametersBooleanWhen true, required API endpoint parameters are validated to be not null
PreserveParameterOrderBooleanWhen true, parameter order is tried to be preserved in endpoints and models
TimeoutFloatWhen true the requests will timeout after the specified duration
EnableAdditionalModelPropertiesBooleanWhen true, additional or unknown properties in the response JSON are collected into a dictionary.
BrandLabelStringA string value to brand the generated files. For example: “Acme Corp.”
UserAgentStringA string value to use as user-agent in the API calls. This is useful for analytics and tracking purposes. For example: “SDK V1.1”
ProjectNameStringThe name of the project for the Generated SDKs
CSharpNamespaceStringA valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate.
JavaPackageNameStringA valid Java package name to be used as the base package name. Leave empty or null to automatically generate. This value is applied for both Java and Android code generation templates.
RunscopeEnabledBooleanWhen true Runscope pass-through for traffic monitoring will be enabled
RunscopeBucketStringThis is the Runscope Bucket Key for traffic monitoring
GenerateTravisConfigBooleanWhen true, the Travis Configuration file will be generated along with the SDK
GenerateCircleConfigBooleanWhen true, the Circle Configuration file will be generated along with the SDK
GenerateAppveyorConfigBooleanWhen true, the Appveyor Configuration file will be generated along with the SDK
GenerateJenkinsConfigBooleanWhen true, the Jenkins Configuration file will be generated along with the SDK

Example:

{
  "CodeGenSettings": {
    "SynchronyMode": 0,
    "ModelSerializationScheme": "Json",
    "ArraySerialization": "Indexed",
    "Nullify404": true,
    "UseHttpMethodPrefix": true,
    "UseModelPrefix": true,
    "UseExceptionPrefix": true,
    "UseEnumPrefix": true,
    "UseControllerPrefix": true,
    "UseConstructorsForConfig": true,
    "Timeout": 0.1,
    "AndroidUseAppManifest": true,
    "iOSUseAppInfoPlist": true,
    "iOSGenerateCoreData": true,
    "CollapseParamsToArray": true,
    "RunscopeEnabled": true,
    "RunscopeBucket": "key",
    "AndroidHttpClient": "UNIREST",
    "ObjCHttpClient": "UNIREST",
    "CSharpHttpClient": "UNIREST",
    "CSharpNamespace": "Root",
    "JavaPackageName": "Root",
    "JavaUsePropertiesConfig": false,
    "PHPHttpClient": "UNIREST",
    "BrandLabel": "Label",
    "UserAgent": "User",
    "ProjectName": "Calculator",
    "EnableAdditionalModelProperties": true,
    "PreserveParameterOrder": true,
    "ValidateRequiredParameters": true,
    "AppendContentHeaders": true,
    "GenerateInterfaces": true,
    "UseCommonSDKLibrary": true,
    "ParameterArrayFormat": 2,
    "GenerateTravisConfig": true,
    "GenerateCircleConfig": true,
    "GenerateAppveyorConfig": true,
    "GenerateJenkinsConfig": true,
    "EnableLogging": false,
    "EnableHttpCache": false,
    "EnablePHPComposerVersionString": false
  }
}

Import Settings

These settings allows you to configure the import through various options e.g. settings that lets you override names of components, etc.

Import Settings Object

The available properties and their respective types are as follows:

SettingTypePurpose
PreferJsonSchemaNameOverTitleBooleanBy default, if a title is specified in a JSON Schema definition we consider this as the model name. However, if this flag is set to true, we give precedence to the definition name instead of the one specified using property title.
AppendParentNameForClashesBooleanBy default 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 to true, the name of the parent component is appended with the name instead.

Note   This is currently supported only for import from Swagger v.2.0.

AutoGenerateTestCasesBooleanFor several formats like OpenAPI (v3.0), API Blueprint, RAML, Postman and HAR, we support auto-generating test cases from request/response examples (if any are present). By default, this will be enabled but can be disabled by setting this flag to false.

Example:

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

Export Settings

These settings lets you configure export to various formats e.g. enabling/disabling extensions when exporting to Swagger.

Export Settings Object

The available properties and their respective types are as follows:

Settings TypeTypePurpose
ExportExtensionsBooleanIf true, any extensions, if supported in the selected export format, will be exported to the output file.
GenerateModelSamplesBooleanBy default, when exporting to Postman (v1.0,2.0), parameter/request/response samples will be auto-generated (where needed) except when importing from WSDL or WADL. Sample generation can be enabled/disabled using this flag.

Example:

{
    "ExportSettings": {
        "ExportExtensions": true,
        "GenerateModelSamples": true
    }
}

Have questions? Submit a request.