Skip to main content

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:

SettingTypePurpose
GENERATEASYNCCODEBooleanWhen true, the CodeGen engine generates asynchronous C# and Java code.
USEMETHODPREFIXBooleanWhen true, HTTP verbs are used as prefix for generated controller methods.
USEMODELPOSTFIXBooleanWhen true, a postfix "Model" is appended to all classes generated from schemas.
USECONTROLLERPOSTFIXBooleanWhen true, a postfix "Controller" is appended to all controllers generated from path groups.
USEENUMPOSTFIXBooleanWhen true, a postfix "Enum" is appended to all enumerations lifted from "allowedValues".
USECONSTRUCTORSFORCONFIGBooleanWhen true, configuration values e.g., authentication credentials, are accepted as controller constructor parameters. Otherwise, these values generate variables in a Configuration class.
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.
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.
COLLECTPARAMETERSBooleanWhen 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.
CSHARPDEFAULTNAMESPACEStringA valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate.
JAVADEFAULTNAMESPACEStringA 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.
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.
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.
PHPCOMPOSERPACKAGENAMEStringThis will set the name in composer.json file for PHP SDKs. You must provide a string with the format your-vendor-name/package-name.
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"
ENABLEADDITIONALMODELPROPERTIESBooleanWhen true, additional or unknown properties in the response JSON are collected into a dictionary.
GENERATEINTERFACESBooleanWhen true, interfaces for controller classes are generated in the generated SDKs
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
TIMEOUTFloatWhen true, the requests will timeout after the specified duration
PROJECTNAMEStringThe name of the project for the Generated SDKs
USECOMMONSDKLIBRARYBooleanWhen true, a common library comprising of common classes is used by the generated SDKs
ARRAYSERIALIZATIONStringFormat 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