Skip to main content

SDK Generation Overview

Apart from a good developer experience, APIMatic offers SDK Generation for your APIs to help accelerate the API consumption process. You can seamlessly integrate code generation into your CI/CD pipelines so that every time your API is updated or versioned, the changes are reflected in an automatically generated SDK. This allows releasing APIs or microservices frequently without any breaking changes.
APIMatic CodeGen Engine offers SDK generation in the following languages:

  • Python
  • .NET
  • Ruby
  • Java
  • PHP
  • TypeScript
  • Go (Alpha Version)

To aid quicker API consumption, APIMatic-generated SDKs come with utility classes, authentication helpers and configuration files. They have strict language bindings, so developers can directly use language objects and functions to interact with the API. Moreover, the SDKs are designed following the latest coding standards, and support all latest language versions and dependencies.

note

To get complete detail on all the features that SDKs provide, go to the SDK Features Docs.

Customizable CodeGen Settings​

Furthermore, API providers can customize code generation using code generation settings, like generic code styling settings, asynchronous/synchronous code generation and advanced documentation generation. These settings can be specified in two ways:

How Does SDK Generation Work?​

The code generation process starts with an input API definition file. This file can be in any of the supported API definition formats like OpenAPI, RAML or API Blueprint and more.

APIMatic SDK Lifecycle

Step 1: API Transformation​

This step transforms the input API definition file into APIMatic's representation format (a.k.a. APIMatic format). Transformation only takes place if you are generating SDKs from an existing API or importing your API, and the API definition in either case is not in APIMatic format. The APIMatic format contains useful information for SDK generation that is not available in other API definition formats.

Step 2: API Validation​

After the API definition is transformed into the APIMatic format, it is validated. Validation is a thorough process that involves checking for numerous discrepancies in the API definition like duplicate parameters or missing request body in GET endpoints, etc. This validation runs through basic API settings, server configurations, code generation settings, authentication settings, models, errors and endpoints. The API validator automatically rectifies minor issues like duplicate property names and throws warnings to reflect any changes made. Major issues like invalid test case input result in errors that must be fixed in the API definition. The validation errors are returned in a JSON response object, for example as shown:

{
    "reason":"API validation Failed for Voice",
    "summary":{
        "errors":[
        {
            "message":"The server template parameter <i><code>base_url</code></i> does not have a default value.",
            "hints":[], "filePath":null,
            "startLineNumber":150, "linePositionStart":23,
            "endLineNumber":151, "linePositionEnd":33
        }],
        "warnings":[],
        }
}

Step 3: SDK Generation: The SDK Layout​

Once the API is validated and any issues are resolved, components of the API definition are looped over to generate code representations. While a basic SDK will cater to settings, endpoints and an abstraction layer, APIMatic goes an extra step by mapping your API completely into an SDK. Some important entity conversions from an API specification to an SDK are:

  • Settings -> Configuration files
    All API settings like environment configuration, server information, authentication parameters and more are consolidated in a configuration file in the SDK.

  • Endpoints -> Functions
    Each endpoint of your API maps onto an independent function in the SDK. Note that if you have configured the CodeGen setting for asynchronous code, the SDK will also contain an asynchronous method for each corresponding endpoint. The endpoints are logically grouped together in controller classes (explained below), and contain XML documentation for each parameter and method as provided in the endpoint description in the API definition.

  • Groups -> Controller class files
    If your API contains logically grouping for endpoints, the SDK will automatically group them accordingly into separate Controller classes. Each controller class will then contain all endpoints contained under the same logic as in your API.

  • Models -> Model class files
    The data input is converted into models. Most APIs accept data as either JSON or form-encoded strings. JSON keys are dynamic; once a new instance of the model is created, all values and types for each parameter are shown automatically, making it easier to just select what is required. So the user doesn't have to go through the documentation to find out about the parameters for each model. You can also configure the models to be immutable through the EnableImmutableModels CodeGen setting.

  • Errors -> Exception class files
    If there is an HTTP error, our SDKs raise an exception that can be handled via a unified exception class. Once a user calls a method, the SDK gives an option to handle APIException or IOException. Moreover, if there are any other custom exceptions in the API, they are also included in this Exception class (if you configure the GenerateException CodeGen setting). This means that the user doesn't have to explicitly go through the documentation to find all the ways the SDK will throw an error. Moreover, having the exceptions in a unified place means that exceptions will be handled for all languages in the same way.

Apart from these core files, the following are generated:

  • HTTP abstraction layer: to wrap the HTTP client used by the SDK.
  • Helper class files: to abstract common code from the SDK.
  • Client library interface: to wrap the SDK and make it easier to use. This acts a single gateway for the library, and it holds the state of the SDK. The client acts as a factory for the controllers.
  • Language/platform-dependent files: for Ruby SDKs, gemspec, Gemfile and Rakefile are generated. These files specify SDK dependencies, test commands and other information required to publish the SDK on hosting services like RubyGems.

Step 4: Documentation Generation​

Every generated SDK comes with a language-specific README.md file, as documentation goes hand-in-hand with the SDKs. Depending on your pricing plan, this README file might contain a very basic getting started guide, or comprehensive documentation for the entire SDK. In the latter case, dynamic screenshots specific to the provided API and platform are generated, and help walk a developer through getting started with the SDK. The README also contains complete class reference and code samples for the SDK and guide the user on:

  • Setting up environment (using tool specific IDEs)
  • Initializing the client
  • Creating the controller
  • Calling the endpoints and testing them

Step 5: Packaging​

Once the SDK files are generated, you can opt to proceed with the following:

SDK Features​

The SDKs generated by APIMatic are not just a mapping of the API onto the SDK. The SDKs contain additional functionality that adheres to the best coding practices to make the SDKs as robust and fault-tolerant as possible. This includes features like:

  • Immutable clients
  • Timeout and automatic retries on API call errors
  • Access to HTTP response data
  • Logging events in the API lifecycle
  • Support for sending and receiving XML in the API calls
  • Cancellable API calls for asynchronous endpoints
  • Multipart requests
  • Logging

For complete detail on the latest SDK features, refer to our SDK Features page.