API Blueprint Extensions

APIMatic allows you to specify additional metadata with API Blueprint that will let you configure APIMatic products (including API Transformer, CodeGen, etc.) to produce better results. Some of the extensions also enable you to utilize parameter types for resources that are not natively available in API Blueprint. This documentation will cover all details related to these extensions.

API Version Extension

This extension allows you to specify your API's version which is not supported in API Blueprint by default.

How to Use the Extension?

You can specify the API version in API Blueprint's Metadata section using the VERSION property as follows:

FORMAT: 1A
HOST: http://api.datumbox.com/
VERSION: 2.0.0

CodeGen Settings Extension

These extensions allow customizing the behaviour of APIMatic's Code Generation Engine. You can control the naming conventions, configuration stores and have your custom code branding. These settings are referred by us as the Code Generation Settings and you can find more details on these at Code Generation Settings. Instead of having to import your API Blueprint into APIMatic and then using the Editor UI to specify these settings, you can now utilize these extensions to specify them in your API definition file. A similar extension is also available in OpenAPI/Swagger whose details can be viewed at OpenAPI/Swagger CodeGen Extensions

How to Use the Extension?

We extended the API Blueprint Metadata section to specify additional properties. See example below:

FORMAT: 1A
HOST: http://api.datumbox.com/

GENERATEASYNCCODE: TRUE
USEMETHODPREFIX: TRUE
USEMODELPOSTFIX: TRUE
USECONTROLLERPOSTFIX: TRUE
USEENUMPOSTFIX: TRUE
USECONSTRUCTORSFORCONFIG: TRUE
IOSUSEAPPINFOPLIST: TRUE
IOSGENERATECOREDATA: FALSE
ANDROIDUSEAPPMANIFEST: TRUE
COLLECTPARAMETERS: FALSE
CSHARPDEFAULTNAMESPACE: ACME.CORP.API
JAVADEFAULTNAMESPACE: com.acme.corp.api
APPENDCONTENTHEADERS: TRUE
BRANDLABEL: ACME CORP.
USERAGENT: APIMATIC 2.0
ENABLEADDITIONALMODELPROPERTIES: FALSE
APPLYCUSTOMIZATIONS: [ custom-f3a77d, custom-f3a77h ]


# DatumBox
Datumbox offers a Machine Learning platform composed of 14 classifiers and Natural Language processing functions. 

..............

The various metadata parameters available and their details are given below:

Setting	Type	Purpose
GENERATEASYNCCODE	Boolean	When true, the CodeGen engine generates asynchronous C# and Java code.
USEMETHODPREFIX	Boolean	When true, HTTP verbs are used as prefix for generated controller methods.
USEMODELPOSTFIX	Boolean	When true, a postfix "Model" is appended to all classes generated from schemas.
USECONTROLLERPOSTFIX	Boolean	When true, a postfix "Controller" is appended to all controllers generated from path groups.
USEENUMPOSTFIX	Boolean	When true, a postfix "Enum" is appended to all enumerations lifted from "allowedValues".
USECONSTRUCTORSFORCONFIG	Boolean	When true, configuration values e.g., authentication credentials, are accepted as controller constructor parameters. Otherwise, these values generate variables in a Configuration class.
IOSUSEAPPINFOPLIST	Boolean	When 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.
IOSGENERATECOREDATA	Boolean	When true, iOS CoreData schema and classes are generated.
ANDROIDUSEAPPMANIFEST	Boolean	When true, configuration values e.g., authentication credentials, are expected in AndroidManifest.xml file for the Android SDK. When set, this setting ignores useConstructorsForConfig flag.
COLLECTPARAMETERS	Boolean	When true, operation parameters are expected to passed as a collection. For example in PHP, the generated method expects a Map containing parameters as Key-Value pairs. This is currently implemented for PHP, Python, GO, and Objective-C. When set, this is applied globally on all endpoints/resources.
CSHARPDEFAULTNAMESPACE	String	A valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate.
JAVADEFAULTNAMESPACE	String	A 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.
APPENDCONTENTHEADERS	Boolean	When 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.
ENABLEPHPCOMPOSERVERSIONSTRING	Boolean	When 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.
PHPCOMPOSERPACKAGENAME	String	This will set the name in composer.json file for PHP SDKs. You must provide a string with the format your-vendor-name/package-name.
BRANDLABEL	String	A string value to brand the generated files. For example: "Acme Corp."
USERAGENT	String	A string value to use as user-agent in the API calls. This is useful for analytics and tracking purposes. For example: "SDK V1.1"
ENABLEADDITIONALMODELPROPERTIES	Boolean	When true, additional or unknown properties in the response JSON are collected into a dictionary.
GENERATEINTERFACES	Boolean	When true, interfaces for controller classes are generated in the generated SDKs
NULLIFY404	Boolean	When true, null response will be returned on the HTTP status code 404
VALIDATEREQUIREDPARAMETERS	Boolean	When true, required API endpoint parameters are validated to be not null
TIMEOUT	Float	When true, the requests will timeout after the specified duration
PROJECTNAME	String	The name of the project for the Generated SDKs
USECOMMONSDKLIBRARY	Boolean	When true, a common library comprising of common classes is used by the generated SDKs
ARRAYSERIALIZATION	String	Format of serialization of arrays in form and query parameters. Valid values are Indexed, UnIndexed, Plain, CSV, TSV, PSV
APPLYCUSTOMIZATIONS	[String]	List of customer-specific customizations to apply.

Parameter Type Extensions

Number Extensions

One of the primitive type that Blueprint offers for resource parameters is number. However, Blueprint does not natively support numbers of precision types e.g. decimal/floating point numbers. APIMatic extension allows you to further categorize number types as Long, Precision, Integers. By default, the numbers in Blueprint will be considered as Precision during import. However, you can specify them as Long or Integer as follows:

• To specify number parameters of type Long, use {LONG} in the description for your parameters e.g here userId will be treated as Long.

+ Parameters
    + userId: 1 (required, number) - {LONG} User ID

• To specify number parameters of type Integer use {INT} in the description for your parameters e.g. here accountId will be treated as Integer

+ Parameters
    + accountId: 1 (required, number) - {INT} Account ID

DateTime Extensions

In Blueprint if you want to have a parameter of type date you will need to use type string and declare the parameter as follows:

+ dateparam: `2015-05-05T12:30:00` (optional, string)

During import, this parameter will not be treated any different from other parameters of type string. In order to utilize the APIMatic DateTime types (Date, DateTime) you can use the following extensions:

• To specify a parameter as DateTime (that contains both date and time) use {DATETIME} in the description for the parameter e.g.

+ datetimeparam: `2015-05-05T12:30:00` (optional, string) - {DATETIME} This is a datetime parameter

• To specify a parameter as Date (in which time is treated as null) use {DATE} in the description for the parameter e.g.

+ dateparam: `2015-05-05` (optional, string) - {DATE} This is a date parameter

File Type Extension

There is no native support in API Blueprint for parameters of type File. If your API makes use of parameters of type File and you intend to utilize APIMatic File type you can use our file type extension in API Blueprint. APIMatic will then automatically extract the type information from the extension during any of the conversions/imports. Just use {FILE} in the description for the parameter. In the following example, the parameter toUpload will be treated as a File parameter located in the Form data.

+ Parameters
    + toUpload (string, required) - {FILE} File to upload.

For more details on the field types available in APIMatic, please visit Field Types

URI Parameter Extensions

API Blueprint does not natively support complex type URI parameters e.g. you cannot have array URI parameters. We, however, allow you to specify array URI parameters by using the {ARRAY} extension in the parameter description. APIMatic will then treat these parameters as arrays e.g. here arrayNumber will be treated as an array of type number

+ Parameters
    + arrayNumber: 1 (required, number) - {ARRAY} parameter is a number array