An Insight into APIMatic’s Autogenerated SDKs

Arooj Arshad
Updated on

Generate SDK

How can you reduce client onboarding of your API so that the API user quickly gets to their first “Hello World”? One definitive way is to provide an SDK for a developer’s technology stack so that they can easily integrate your APIs onto their native platforms. By providing an SDK, it becomes much simpler for a developer to integrate your API 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 or API references. You need to attract developers to enable them to comfortably play around with your code, and this is what APIMatic SDKs help with.

APIMatic as a Code Generator

APIMatic autogenerates SDKs for APIs automatically in all major programming languages so that developers can consume APIs in their favorite development environment with less code, less effort, and more fun. These comprehensive SDKs help accelerate the API consumption process as they can be automatically generated and shipped along with your latest API update. They accurately map your API definition files into their respective classes and controllers while adhering to the best coding practices. APIMatic further provides flexibility to customize code generation through Customizable CodeGen Settings. APIMatic generates SDKs 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 more detailed pros and cons of manually generating SDKs against autogenerating them, read here on The Great SDK Battle: Build vs Buy.

How does APIMatic Autogenerate SDKs?

SDK generation is a tricky challenge for API providers. On one side, you want to keep SDKs with minimal code and dependencies and on the other hand, you want to customize the generated code according to the needs of the developers. APIMatic gives you an easy solution by providing autogenerated SDKs for your APIs.

APIMatic’s Code Generation Engine follows 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: This step transforms 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: After an input file is transformed into APIMatic’s format, it is validated. The validation process includes checking for syntactical and semantical discrepancies in the API definition and shows critical warnings and errors to be fixed before SDK generation can proceed.
  • SDK Generation: Now, 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: Every generated SDK also includes a README.md file. The README contains complete class reference and code samples for the SDK and guides the user on setting up the environment (using tool-specific IDEs), initializing the client, creating the controller, calling the endpoints, and testing them. 
  • Packaging: After all the SDK files have been generated, there are multiple packaging options available to APIMatic 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’s Autogenerated SDKs 

APIMatic SDKs supports the latest versions and language dependencies, along with features that make them as robust and fault-tolerant as possible.

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 assurity that no method call would mutate its state once the client is instantiated.

Timeout and Retries on API Call Errors

APIMatic generated 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 XML in API Calls

The 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 having to worry about serializing and deserializing the XML data. 

oneOf and anyOf Support

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

Support for Nullable Properties in Models

Java and C# 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

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

Other features in the SDKs include optimized error messages, handling cancellation of API calls, and more. For more information and details on all the features that APIMatic SDKs provide, have a look at our SDK Features List.

How to Generate SDKs from API Definitions?

Next, comes the part where you can generate your SDKs via various options according to your specified use case:

Generate SDKs through Web

You can generate an SDK for any API definition file in your favorite language through our APIMatic dashboard. Select any API or its version from the dashboard and generate the SDK via the ‘Generate’ button. After the validation process, you can choose to download the SDK as a zip file, deploy it to Github or publish it as a package.

                                                                 Generating SDK Options

Generate SDKs through API

You can automate the process of SDK generation using APIMatic’s CodeGen API, by integrating it into your CI/CD pipelines. You can generate SDKs for APIs already imported into APIMatic, any external API, or by 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 

You can also integrate the APIMatic CLI into your CI/CD pipelines for a seamless and automated experience. APIMatic CLI supports all the basic features like validation, transformation, SDK, and documentation generation. You can generate an SDK for your API through the CLI via the apimatic SDK:generate command: 

apimatic-cli command to generate SDK

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 applications and innovative solutions.