An Insight into APIMatic’s Autogenerated SDKs

How can you reduce onboarding time to quickly get the developer to their first “Hello World”? One definitive way is to provide an SDK for a developer’s technology stack. An SDK makes it easy for a developer to integrate the API onto their native platforms in ways that are familiar and well-integrated with their existing toolchain.

In simpler terms, it is no longer enough to expose your API endpoints with just HTTP documentation as an API reference. You need to help developers play around with your code more comfortably. To tackle this scenario, APIMatic SDKs come into the picture!

APIMatic as a Code Generator

APIMatic autogenerates SDKs in multiple languages so developers can consume APIs in their favorite development environment with less code and minimized effort. These comprehensive SDKs help accelerate the API consumption process as they are autogenerated and shipped along with your latest API update. SDKs accurately map your API definition files into their respective classes and controllers while adhering to the best coding practices. APIMatic provides flexibility to customize SDK code generation through Customizable CodeGen Settings and generates them in the following languages:

• PHP
• Ruby
• Python
• C# (.NET)
• Java
• TypeScript

Building and maintaining these feature-packed SDKs from scratch is not easy and requires extensive engineering time and effort. However, autogenerated SDKs can significantly cut down costs and time. For detailed pros and cons of manual and autogeneration of SDKs, read The Great SDK Battle: Build vs Buy.

How does APIMatic Generate SDKs?

SDK generation is a tricky challenge for API providers. On one hand, you want to keep SDKs with minimal code and dependencies; on the other hand, you want to customize the generated code according to the needs of the developers. 

APIMatic Code Generation gives you an easy solution by providing SDKs that follow several steps internally to generate client libraries from API definition files. The code generation process starts with an input API definition file which can be in any of the multiple supported API definition formats like OpenAPI, RAML, API Blueprint, etc.

API Transformation

The first step is to transform the input API definition file into APIMatic’s format which contains useful information for SDK generation that is not available in other API definition formats.

API Validation

The next step is the validation process which includes checking syntactical and semantical discrepancies in the API definition. It also shows critical warnings and errors to be fixed before SDK generation can proceed. For more information, go to Validation Rulesets Docs.

SDK Generation 

Going further, components of the API definition are looped over to generate code representations. While a basic SDK caters 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 definition to an SDK are:

• Settings -> Configuration files: All API settings like environment configuration etc are consolidated in a configuration file.
• Endpoints -> Functions: Each endpoint maps onto an independent function.
• Groups -> Controller class files: Endpoints are automatically grouped into separate Controller classes.
• Models -> Model class files: Data input is converted into models.
• Errors -> Exception class files: Errors are handled as exceptions via a unified exception class. 

Apart from these core files, the CodeGen engine also generates the following utility files:

• HTTP abstraction layer
• Helper class files
• Client library interface
• Language/platform-dependent files

Documentation Generation

Next, every generated SDK includes a README.md file that contains complete class references and code samples for the SDK. It guides in setting up the environment (using tool-specific IDEs), initializing the client, creating the controller, calling the endpoints, and testing them. 

Package Publishing

After all the SDK files have been generated, multiple packaging options are available to the users. You can either get the SDK packaged in a zip file, have it deployed to GitHub, or publish it as a package on platforms like npm, NuGet, RubyGems, and PyPI.

For more detail on the mapping from an API specification file to SDK, please refer to the APIMatic SDK Overview.

Features Supported in APIMatic SDKs 

APIMatic SDKs support the latest versions, and language dependencies and are more than just API wrappers. These SDKs not only deliver full coverage of the API specification but also go beyond providing features that cater to the API consumers who use them in their applications and to the API providers who debug any issues that may arise during their API calls. Hence, making SDKs more robust and fault-tolerant as possible.

API Consumer DX Features

Immutable Clients for Multi-Threading

An Immutable Client does not allow the user of the client to mutate the client (i.e change its state) once it has been created. Client classes of all the SDKs are designed using the immutable design pattern. This gives developers the assurance that once the client has been instantiated, no method call would mutate its state.

oneOf and anyOf Support

Java, Python, and PHP SDKs contain the support of oneOf and anyOf features which gives the ability to create a complex schema or validate a value against multiple criteria.

Timeout and Retries on API Call Errors

SDKs help you write fault-tolerant applications by helping deal with network fault errors. If an API call fails due to network problems, it is retried with an exponentially increasing wait time up to a maximum retry count specified by the user. This is particularly helpful during temporary network outages. 

Support for Nullable Properties in Models

SDKs contain nullable properties in models, so if a user does not assign any value to a property after model instance initialization, a null value will be sent in the HTTP request instead of being skipped altogether.

Access to HTTP Response Data

SDKs allow access to the HTTP response information like response headers, status codes, and body on API calls.

Getting Started Guides

SDKs come bundled with a comprehensive README that contains information about environments, configuration, authentication, and code samples to initialize the client.

Thread-Safe API Calls

SDKs are designed to handle concurrent API calls in a thread-safe manner.

Async Operations

SDKs provide asynchronous methods to call endpoints to fully utilize the potential of async programming.

Extendable Interfaces

SDKs can be configured to generate interfaces for controller classes to extend the functionality of the SDKs.

Logging

Logging can be enabled to diagnose and debug issues in the API calls.

OAuth Support and Utility Methods

All SDKs support popular OAuth flows and provide utility methods to generate or refresh access tokens.

Code Samples and Usage Examples for Every Endpoint and Model

SDKs have detailed documentation on all endpoints and models providing code samples.

Code Style Compliant SDKs

SDKs follow coding style conventions and best practices making the SDK’s code consistent.

API Provider DX Features

Support for XML in API Calls

SDKs contain support for sending and receiving XML in the API calls, alongside JSON. So if your API definition uses XML, it can be imported into APIMatic to generate SDKs without worrying about serializing and deserializing the XML data.

Optimized Error Messages

APIMatic allows defining custom errors that correspond to HTTP response codes other than 200. These errors translate to exception classes in the SDKs and provide meaningful information as to why the API call failed.

Simple Types instead of Enumerations

Simple types like strings or integers in the generated SDKs can be used instead of enumeration types in case you frequently change the definition of the enumerations. 

Deprecating Endpoints

An endpoint that is marked as deprecated will result in a compiler warning or a notice logged to the console.

API Specification Wrapper Features

Endpoints

Endpoints described in the API are automatically generated to controller classes in the generated code, the SDK. It consists of the endpoint name, response type, route, parameters, etc.

Models

Model is a data structure used in API definition that automatically converts to classes in the SDK with its field type as class parameters.

API Error Handling

Errors are defined for particular endpoints with error response types and error type names in the SDK.

Authentication

APIMatic SDKs include various authentication types given below which are automatically generated with the required parameters in a configuration file in the SDK.

• Basic Authentication
• OAuth 2.0
• Custom Query
• Custom Headers

How to Generate SDKs from API Definitions?

You can generate SDKs via various options according to your specified use case:

• Web
• API 
• APIMatic CLI

Generate SDKs through Web

You can generate an SDK for any API definition file in your favorite language through the APIMatic dashboard. Select any API or version from the dashboard and generate the SDK via the Generate button. After the validation process, you can choose to

• Download SDK as a Zip file
• Deploy at Github
• Publish it as a package

Generate SDKs through API

You can automate SDK generation by integrating it into your CI/CD pipelines via APIMatic’s CodeGen API. You can generate SDKs for APIs:

• Already imported into APIMatic
• Any external API
• Specifying a URL

The generated SDKs are downloaded as a zip file in your system.

{
    string apiEntityId = "apiEntityId2"; 
    Platforms template = Platforms.CSNETSTANDARDLIB; 

    try {    
            APIEntityCodeGeneration result = await codeGenerationImportedApisController
                                                        .GenerateSDKAsync(apiEntityId, template); 
        } 
    catch (ApiException e) {};
}

Generate SDKs through APIMatic CLI 

APIMatic CLI offers all the basic features by providing automation in the form of 

• API Validation
• API Transformation
• SDK Generation
• Documentation Generation

You can integrate APIMatic CLI into your CI/CD pipelines for a seamless and automated experience. You can generate an SDK for your API through the CLI via the apimatic SDK:generate command:

For more details, read our Generating SDKs via APIMatic Docs.

Wrapping it Up!

Creating SDKs in multiple languages is quite resource-intensive and expensive. Good SDKs save both time and cognitive effort when integrating with a provider’s API. This is why APIMatic’s CodeGen engine gives you the maximum advantage in creating SDKs and takes care of all the SDK generation and maintenance work behind the scenes while your developers can focus on their innovative solutions. Try out APIMatic now and feel free to contact us for any queries!