Behind the Scenes of SDK Generation

Automated SDK generation is a tricky challenge; on one hand, you want to keep SDKs lean with minimal code and dependencies and on the other hand, you want to allow API providers to customize the generated code according to the needs of their developers such that SDKs can be more than mere language wrappers of an API.

In this post, we will share how our code generation engine works and how we have managed to allow code customizations without letting API providers be bogged down in manual efforts.

APIMatic’s Code Generation Engine follows a number of steps to generate client libraries from API description files. The code generation process starts with an input API description file. This file can be in any of the multiple API description formats we support like OpenAPI, RAML, or API Blueprint, etc.

Step 1: Transformation

The first step is the conversion or transformation of the input API description file into our own representation format, internally known as Standard Description Language (SDL). This is the same format that is publicly referred to as the APIMatic format. Transformation is only done if the API description is not already in the APIMatic format and you’re generating from the API or importing your API description into our API description editor. The APIMatic format has evolved over time to capture information that is useful for SDK generation but is otherwise missing in API description formats. It also serves as a superset of API description features over other formats.

Step 2: Validation (and correction)

After an input file is transformed into APIMatic’s format, it is then validated. Validation is quite a thorough process comprising of a large number of sub-steps. It starts with the validation of basic API settings, server configurations, and code generation settings. Authentication settings are validated after that, followed by validation of models, errors, and endpoints.

Our API validator aids the user by automatically rectifying small issues like duplicate property names and throws warnings to reflect any changes made. Bigger issues (for example, invalid test case input) result in errors which the user needs to fix in their API description.

Step 3: SDK Generation

Following the validation and correction of an API description is the code generation step. Different parts of the API description are looped over and code representations are generated. Some important entity conversions from an API description to an SDK are:

• Settings -> Configuration files
• Endpoints -> Functions
• Groups -> Controller class files
• Models -> Model class files
• Errors -> Exception class files

Along with these core files, an HTTP abstraction layer is generated to wrap the HTTP client is used by the SDK so as to facilitate the user in case he decides to use a different client. One or more helper class files are generated which abstract out a lot of the common code from the SDK and a client library interface is provided to wrap the SDK and make it easier to use. Some language or platform-dependent files are generated as well, for example, gemspec, Gemfile, and Rakefile are generated for Ruby SDKs. 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 includes a README.md file. Depending on the user’s pricing plan, this README file might contain a very basic getting started guide or it may contain detailed and comprehensive documentation for the entire SDK. In the latter case, dynamic screenshots specific to the user’s API are generated and uploaded to our servers. These screenshots walk a developer through getting started with the SDK and are linked in the markdown README file. The README also contains a complete class reference and code samples for the SDK and creates a delightful developer experience when rendered.

Step 5: 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 or have it deployed to Github.

The output of the process may be a zipped SDK available for download, a new branch on the user’s Github repository or, our latest offering, a complete Developerless API Portal.

SDKs, not mere wrappers

The SDKs generated by our code generation engine come with utility classes, authentication helpers, and configuration files to aid usage. They provide strict language bindings so developers never have to deal with HTTP or JSON, but instead communicate with the API using language objects and functions. They are also built around  SOLID  software design principles to allow easy extension in functionality.

We allow API providers to customize code generation using simple code generation settings. From generic code styling settings like class naming to advance code customization settings like asynchronous or synchronous code generation and advanced documentation generation; we have a lot to offer.

Is automatic SDK generation for you?

SDKs help API providers increase API adoption by enabling developers from different platforms or languages to get started with their API quickly. With instant SDK generation times and cheap costs, code generation engines might be the obvious way to go if you need SDKs for your APIs.

In spite of all the benefits of generating SDKs using a code generation engine, there are certain scenarios where it might be wiser to write SDKs manually. One example is when you are planning to put some specific business logic like complex cryptographic logic in your SDKs to simplify API design or to exploit client-side processing to maximize API scalability. We counter this to some extent by providing HTTP abstraction and before and after request hooks in SDK code to allow wrappers to be written over generated code. Still, it is up to the API provider to decide if that is enough for their specific use case.

It is important to delineate your requirements before deciding how you will provide SDKs to developers using your API. Our team is always available for discussion; don’t hesitate getting in touch if you’re still unsure about code generation being the right fit for you.