Getting started

Code-Gen and Transformation as a service

APIMatic is a highly customizable automatic code and documentation generator for RESTful APIs using machine-readable API descriptions. This REST API provides programmatic access to APIMatic's CodeGen and Transformation engine. The users can perform the following tasks using this REST API

  • Generate client side libaries and documentation in 10 programming languages.
  • Transform API descriptions to and from all popular description formats
  • Validate API descriptions

API Descriptions

APIMatic takes in machine readable descriptions as inputs. The following formats are supported:

  • APIMatic
  • WADL
  • OAS 1.2, 2.0, 3.0 (JSON And YAML)
  • RAML
  • API Blueprint
  • IODocs
  • Google Discovery
  • Mashape
  • HAR
  • Postman
  • WSDL

Although most API descriptions can be used, not all API descriptions 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.

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 the numerous codegen settings which enable customization of the output code.

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, a API Key is used, which can be retrieved using the API context menu. This API Key is used as a unique reference identifier to perform various options.

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

API description files

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 make use of these extensive codegen settings. For using these codegen settings with other formats use our format extensions. More information on the available extensions can be found here:

Format Extensions
OAS 1.2 , 2.0 & 3.0 Swagger Extensions
API Blueprint API Blueprint Extensions

Code-Gen As A Service

Code-Gen logo APIMatic's Code-Gen as a Service is a highly customizable Code-Gen-Engine, which simplifies API consumption by generating high-quality SDKs, code samples, dynamic docs and test cases using API descriptions. This enables API providers to help their developers consume their APIs in a language of their choice. Using this REST API this highly useful Code-Gen engine can be incorporated into your CI cycle, greatly reducing time and effort. The list of supported languages are:

  • .Net
    • .Net Standard Library
    • Portable Class Library
  • Android
  • Java
  • PHP
  • Python
  • Ruby
  • Objective-C
  • AngularJS
  • NodeJS
  • Go

API Transformer

Convertron 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, without any added effort. 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

API Validator

The verbose validation API can be used to identify and fix errors in your API descriptions. This API supports all formats listed in the API Descriptions section.

How to Build

You must have Python 2 >=2.7.9 or Python 3 >=3.4 installed on your system to install and run this SDK. This SDK package depends on other Python packages like nose, jsonpickle etc. These dependencies are defined in the requirements.txt file that comes with the SDK. To resolve these dependencies, you can use the PIP Dependency manager. Install it by following steps at https://pip.pypa.io/en/stable/installing/.

Python and PIP executables should be defined in your PATH. Open command prompt and type pip --version. This should display the version of the PIP Dependency Manager installed if your installation was successful and the paths are properly defined.

  • Using command line, navigate to the directory containing the generated files (including requirements.txt) for the SDK.
  • Run the command pip install -r requirements.txt. This should install all the required dependencies.

Building SDK - Step 1

How to Use

The following section explains how to use the Apimatic SDK package in a new project.

1. Open Project in an IDE

Open up a Python IDE like PyCharm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Open project in PyCharm - Step 1

Click on Open in PyCharm to browse to your generated SDK directory and then click OK.

Open project in PyCharm - Step 2

The project files will be displayed in the side bar as follows:

Open project in PyCharm - Step 3

2. Add a new Test Project

Create a new directory by right clicking on the solution name as shown below:

Add a new project in PyCharm - Step 1

Name the directory as "test"

Add a new project in PyCharm - Step 2

Add a python file to this project with the name "testsdk"

Add a new project in PyCharm - Step 3

Name it "testsdk"

Add a new project in PyCharm - Step 4

In your python file you will be required to import the generated python library using the following code lines

from apimatic.apimatic_client import ApimaticClient

Add a new project in PyCharm - Step 4

After this you can write code to instantiate an API client object, get a controller object and make API calls. Sample code is given in the subsequent sections.

3. Run the Test Project

To run the file within your test project, right click on your Python file inside your Test project and click on Run

Run Test Project - Step 1

How to Test

You can test the generated SDK and the server with automatically generated test cases. unittest is used as the testing framework and nose is used as the test runner. You can run the tests as follows:

  1. From terminal/cmd navigate to the root directory of the SDK.
  2. Invoke pip install -r test-requirements.txt
  3. Invoke nosetests

Initialization

Authentication

In order to setup authentication and initialization of the API client, you need the following information.

Parameter Description
basic_auth_user_name The username to use with basic authentication
basic_auth_password The password to use with basic authentication

API client can be initialized as following.

# Configuration parameters and credentials
basic_auth_user_name = 'basic_auth_user_name' # The username to use with basic authentication
basic_auth_password = 'basic_auth_password' # The password to use with basic authentication

client = ApimaticClient(basic_auth_user_name, basic_auth_password)

Class Reference

List of Controllers

Class: ValidatorController

Get controller instance

An instance of the ValidatorController class can be accessed from the API Client.

 validator_controller = client.validator

Method: validate_using_file

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.

def validate_using_file(self,
                            body)

Parameters

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

Example Usage

body = open("pathtofile", 'rb')

result = validator_controller.validate_using_file(body)

Method: validate_using_api_key

Tags: Skips Authentication

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

def validate_using_api_key(self,
                               apikey)

Parameters

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

Example Usage

apikey = 'zfd8HsAb24Jcm0DFXpYwh4ucxAMmXhEygcXsdxtf7HNZhHCaSOM1e4otNoZqHEwG'

result = validator_controller.validate_using_api_key(apikey)

Method: validate_using_url

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).

def validate_using_url(self,
                           description_url)

Parameters

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

Example Usage

description_url = 'https://github.com/raml-org/raml-examples/blob/master/helloworld/helloworld.raml'

result = validator_controller.validate_using_url(description_url)

Back to List of Controllers

Class: APITransformerController

Get controller instance

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

 api_transformer_controller = client.api_transformer

Method: transform_using_api_key

Tags: Skips Authentication

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

def transform_using_api_key(self,
                                format,
                                apikey)

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

format = APIDescriptionFormat.WEB SERVICES DESCRIPTION LANGUAGE
apikey = 'zfd8HsAb24Jcm0DFXpYwh4ucxAMmXhEygcXsdxtf7HNZhHCaSOM1e4otNoZqHEwG'

result = api_transformer_controller.transform_using_api_key(format, apikey)

Errors

Error Code Error Description
400 Bad Request

Method: transform_using_url

Transforms the API description from the given URL to the specified format. The API description format of the provided file will be detected automatically. The converted file is returned as the response.

def transform_using_url(self,
                            format,
                            description_url)

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

format = APIDescriptionFormat.SWAGGER
description_url = 'https://github.com/raml-org/raml-examples/blob/master/helloworld/helloworld.raml'

result = api_transformer_controller.transform_using_url(format, description_url)

Errors

Error Code Error Description
400 Bad Request

Method: transform_using_file

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.

def transform_using_file(self,
                             format,
                             file)

Parameters

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

Example Usage

format = APIDescriptionFormat.APIMATIC
file = open("pathtofile", 'rb')

result = api_transformer_controller.transform_using_file(format, file)

Errors

Error Code Error Description
400 Bad Request

Back to List of Controllers

Class: ClientGeneratorController

Get controller instance

An instance of the ClientGeneratorController class can be accessed from the API Client.

 client_generator_controller = client.client_generator

Method: generate_using_url

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.

def generate_using_url(self,
                           template,
                           name,
                           description_url)

Parameters

Parameter Tags Description
template Required The template 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

Example Usage

template = SDKTemplate.CSHARP WINDOWS PLATFORM LIBRARY
name = 'Test'
description_url = 'https://github.com/raml-org/raml-examples/blob/master/helloworld/helloworld.raml'

result = client_generator_controller.generate_using_url(template, name, description_url)

Errors

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

Method: generate_using_file

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.

def generate_using_file(self,
                            name,
                            template,
                            body)

Parameters

Parameter Tags Description
name Required The name of the API being used for code generation
template Required The template to use for code generation
body Required The input file to use for code generation

Example Usage

name = 'name'
template = SDKTemplate.CSHARP PORTABLE LIBRARY
body = open("pathtofile", 'rb')

result = client_generator_controller.generate_using_file(name, template, body)

Errors

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

Method: generate_using_api_key

Tags: Skips Authentication

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.

def generate_using_api_key(self,
                               apikey,
                               template)

Parameters

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

Example Usage

apikey = 'zfd8HsAb24Jcm0DFXpYwh4ucxAMmXhEygcXsdxtf7HNZhHCaSOM1e4otNoZqHEwG'
template = SDKTemplate.CSHARP PORTABLE LIBRARY

result = client_generator_controller.generate_using_api_key(apikey, template)

Errors

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

Back to List of Controllers