Getting started

APIMATIC CodeGen as a Service

APIMATIC is an automatic code generator for RESTful APIs. This API exposes the access to its underlying code generation engine. We currently support the following format for API descriptions, API Blueprint, RAML, Google API Discovery, IODocs, WADL, and Swagger. Although most API descriptions can be used, not all API decsriptions are written well-enough for automatic code generation and may fail the code generation process. For this purpose, we have provided a verbose validation API, which can be used to improve your API description.

Looking for a way to convert between API description formats like Swagger and API Blueprint? Try APIMATIC's Transformer API or it's web version at Transformer.

APIMATIC works in two modes i.e., perform operations on pre-configured API descriptions, and perform operations on API descriptions sent on the fly with requests. The later mode of operations has its limitations with respect to the customization of the generated code through our codegen settings.

See this article for more information about customization of the output code.

Working with pre-configured API descriptions

This mode of operation is useful where APIs are stable and therefore can be pre-configured in APIMATIC. You can always update an API description in APIMATIC using the API Editor by clicking on the Edit button. When working with stored API descriptions, pre-configured codegen settings are used that allow customization of the generated output. In order to uniquely identify the API to perform operations on, an API Key is used, which can be retrieved using the API context menu. This API Key is a secret value and therefore operations on pre-configured API descriptions do not require authentication.

See this article on how to get your API Key from APIMATIC.

Working with API descriptions documents

This mode of operation is useful in cases where API descriptions are automatically generated from a process or external source and cannot be pre-configured in APIMATIC. In this case code generation uses the default codegen settings. However, if custom codegen settings are desired you may use the APIMATIC format for generating your API descriptions, which contains nested codegen settings. For getting the full benefit of our advanced features in our code generator, you must either pre-configure your API, or use APIMATIC format for API description.

APIMATIC API Transformer

APIMATIC Transformer allows its users to convert between different API description formats e.g. Swagger, RAML, etc. This enables the user to benefit from a wide range of tools available associated with any format, not just one. The complete list of supported formats of Transformer are:

Inputs | Outputs ------------------ | ------------------- API Blueprint | API Blueprint Swagger v.1.2 | Swagger 1.2 Swagger 2.0 (JSON and YAML) | Swagger 2.0 (JSON, YAML) Open API v.3.0 | Open API 3.0 WADL 2009 (W3C) | WADL 2009 (W3C) WSDL (W3C) | WSDL (W3C) Google Discovery | RAML 0.8 - 1.0 RAML 0.8 - 1.0 | Postman Collection 1.0 - 2.0 I/O Docs - Mashery | APIMATIC Format HAR 1.2 | Postman Collection 1.0 - 2.0 | APIMATIC Format | Mashape |

How to Build

The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here

NPM is installed by default when Node is installed

To check if node and npm have been successfully installed, write the following commands in command prompt:

• node --version
• npm -version

Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):

npm install

This will install all dependencies in the node_modules folder.

Once dependencies are resolved, you will need to move the folder APIMATICCodeGenAndTransformerAPILib in to your node_modules folder.

How to Use

The following section explains how to use the library in a new project.

1. Open Project Folder

Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on File and select Open Folder.

Select the folder of your SDK and click on Select Folder to open it up in Sublime Text. The folder will become visible in the bar on the left.

2. Creating a Test File

Now right click on the folder name and select the New File option to create a new test file. Save it as index.js Now import the generated NodeJS library using the following lines of code:

var lib = require('lib');

Save changes.

3. Running The Test File

To run the index.js file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:

node index.js

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

1. Navigate to the root directory of the SDK folder from command prompt.
2. Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha APIMATIC CodeGen and Transformer APIController to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

Initialization

Authentication

In order to setup authentication in the API client, you need the following information.

| Parameter | Description | |-----------|-------------| | basicAuthUserName | The username to use with basic authentication | | basicAuthPassword | The password to use with basic authentication |

API client can be initialized as following:

const lib = require('lib');

// Configuration parameters and credentials
lib.Configuration.basicAuthUserName = "basicAuthUserName"; // The username to use with basic authentication
lib.Configuration.basicAuthPassword = "basicAuthPassword"; // The password to use with basic authentication

Class Reference

List of Controllers

• CodeGenerationController
• APITransformerController
• APIDescriptionValidationController

CodeGenerationController

Get singleton instance

The singleton instance of the CodeGenerationController class can be accessed from the API Client.

var controller = lib.CodeGenerationController;

usingApikeyAsBinary

Convert an API from the user's account using the API's API Integration Key. The response is generated zip file as per selected template.

Note: This endpoint does not require Basic Authentication.

function usingApikeyAsBinary(apikey, template, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | apikey | Required | The API Key of the pre-configured API | | template | Required | The template to use for code generation | | dl | Optional DefaultValue | Optional |

Example Usage

    var apikey = 'apikey';
    var template = Object.keys(template)[0];
    var dl = 71;

    TestHelper.getFileContents('url', function(data) {
        controller.usingApikeyAsBinary(apikey, template, dl, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

usingApikeyAsString

The code generation endpoint. The response is a path to the generated zip file relative to https://apimatic.io/

Note: This endpoint does not require Basic Authentication.

function usingApikeyAsString(apikey, template, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | apikey | Required | The API Key of the pre-configured API | | template | Required | The template to use for code generation | | dl | Optional DefaultValue | Optional |

Example Usage

    var apikey = 'apikey';
    var template = Object.keys(template)[0];
    var dl = 71;

    controller.usingApikeyAsString(apikey, template, dl, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

usingUrlAsBinary

Download API description from the given URL and convert it to the given format. The API description format of the provided file will be detected automatically. The response is generated zip file as per selected template.

function usingUrlAsBinary(template, format, name, descriptionUrl, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | template | Required | The template to use for code generation | | format | Required | The format of the API description to use for code generation | | name | Required | The name of the API being used for code generation | | descriptionUrl | Required | The absolute public Uri for an API description doucment | | dl | Optional DefaultValue | Optional |

Example Usage

    var template = Object.keys(template)[0];
    var format = Object.keys(format)[0];
    var name = 'name';
    var descriptionUrl = 'descriptionUrl';
    var dl = 71;

    TestHelper.getFileContents('url', function(data) {
        controller.usingUrlAsBinary(template, format, name, descriptionUrl, dl, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

usingUrlAsString

The code generation endpoint. The response is a path to the generated zip file relative to https://apimatic.io/

function usingUrlAsString(template, format, name, descriptionUrl, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | template | Required | The template to use for code generation | | format | Required | The format of the API description to use for code generation | | name | Required | The name of the API being used for code generation | | descriptionUrl | Required | The absolute public Uri for an API description doucment | | dl | Optional DefaultValue | Optional |

Example Usage

    var template = Object.keys(template)[0];
    var format = Object.keys(format)[0];
    var name = 'name';
    var descriptionUrl = 'descriptionUrl';
    var dl = 71;

    controller.usingUrlAsString(template, format, name, descriptionUrl, dl, function(error, response, context) {

    
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

usingFileAsBinary

The code generation endpoint! Upload a file and convert it to the given format. The API description format of uploaded file will be detected automatically. The response is generated zip file as per selected template.

function usingFileAsBinary(name, format, template, body, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | name | Required | The name of the API being used for code generation | | format | Required | The format of the API description to use for code generation | | template | Required | The template to use for code generation | | body | Required | The input file to use for code generation | | dl | Optional DefaultValue | Optional |

Example Usage

    TestHelper.getFilePath('url', function(data) {
        var name = 'name';
    var format = Object.keys(format)[0];
    var template = Object.keys(template)[0];
    var body = data;
    var dl = 71;

        controller.usingFileAsBinary(name, format, template, body, dl, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

usingFileAsString

The code generation endpoint. The response is a path to the generated zip file relative to https://apimatic.io/

function usingFileAsString(name, format, template, body, dl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | name | Required | The name of the API being used for code generation | | format | Required | The format of the API description to use for code generation | | template | Required | The template to use for code generation | | body | Required | The input file to use for code generation | | dl | Optional DefaultValue | Optional |

Example Usage

    TestHelper.getFilePath('url', function(data) {
        var name = 'name';
    var format = Object.keys(format)[0];
    var template = Object.keys(template)[0];
    var body = data;
    var dl = 71;

        controller.usingFileAsString(name, format, template, body, dl, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 401 | Unauthorized: Access is denied due to invalid credentials. | | 412 | Precondition Failed |

Back to List of Controllers

APITransformerController

Get singleton instance

The singleton instance of the APITransformerController class can be accessed from the API Client.

var controller = lib.APITransformerController;

convertFileDownloadedFromDescriptionURLToFormat

Download API description from the given URL and convert it to the given format. The API description format of the provided file will be detected automatically. The converted file is returned as the response.

function convertFileDownloadedFromDescriptionURLToFormat(format, descriptionUrl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | format | Required | The API format to convert to | | descriptionUrl | Required | The URL where the API description will be downloaded from |

Example Usage

    var format = Object.keys(format_transformer)[0];
    var descriptionUrl = 'descriptionUrl';

    TestHelper.getFileContents('url', function(data) {
        controller.convertFileDownloadedFromDescriptionURLToFormat(format, descriptionUrl, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Bad Request |

convertUploadedFileToFormat

Upload a file and convert it to the given format. The API description format of the uploaded file will be detected automatically. The converted file is returned as the response.

function convertUploadedFileToFormat(format, file, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | format | Required | The API format to convert to | | file | Required | The input file to convert |

Example Usage

    TestHelper.getFilePath('url', function(data) {
        var format = Object.keys(format_transformer)[0];
    var file = data;

        controller.convertUploadedFileToFormat(format, file, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Bad Request |

convertAnUploadedAPIDescriptionToFormatUsingAPIsApiIntegrationKey

Convert an API from the user's account using the API's Api Integration Key. The converted file is returned as the response.

Note: This endpoint does not require Basic Authentication.

function convertAnUploadedAPIDescriptionToFormatUsingAPIsApiIntegrationKey(format, apikey, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | format | Required | The API format to convert to | | apikey | Required | Apikey of an already uploaded API Description on APIMATIC |

Example Usage

    var format = Object.keys(format_transformer)[0];
    var apikey = 'apikey';

    TestHelper.getFileContents('url', function(data) {
        controller.convertAnUploadedAPIDescriptionToFormatUsingAPIsApiIntegrationKey(format, apikey, function(error, response, context) {

        });
    });

Errors

| Error Code | Error Description | |------------|-------------------| | 400 | Bad Request |

Back to List of Controllers

APIDescriptionValidationController

Get singleton instance

The singleton instance of the APIDescriptionValidationController class can be accessed from the API Client.

var controller = lib.APIDescriptionValidationController;

validateAnAPIDescriptionFromUri

This endpoint can be used to validate an API description document on the fly from its public Uri, and see detailed error messages along with any warnings or useful information. This endpoint is useful for API descriptions with relative links e.g., includes (RAML) and paths (swagger).

function validateAnAPIDescriptionFromUri(descriptionUrl, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | descriptionUrl | Required | The absolute public Uri for an API description doucment |

Example Usage

    var descriptionUrl = 'descriptionUrl';

    controller.validateAnAPIDescriptionFromUri(descriptionUrl, function(error, response, context) {

    
    });

validateAPreConfiguredAPIDescription

This endpoint can be used to validate a pre-configured API description and see detailed error messages along with any warnings or useful information.

function validateAPreConfiguredAPIDescription(apikey, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | apikey | Required | The API Key of a pre-configured API description from APIMATIC |

Example Usage

    var apikey = 'apikey';

    controller.validateAPreConfiguredAPIDescription(apikey, function(error, response, context) {

    
    });

validateAnAPIDescription

This endpoint can be used to validate an API description document on the fly and see detailed error messages along with any warnings or useful information.

function validateAnAPIDescription(body, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | body | Required | The input file to use for validation |

Example Usage

    TestHelper.getFilePath('url', function(data) {
        var body = data;

        controller.validateAnAPIDescription(body, function(error, response, context) {

        });
    });

Back to List of Controllers