Mehdi Raza Jaffery September 8, 2023

Cover image for Introducing APIMatic Code Generator for GoWe’re APIMatic.io. We generate strongly typed SDKs along with a complete API reference from OpenAPI definitions. If you want to create an SDK for your REST API, check out how to generate one in under a minute. We support generating SDKs for C#, Java, PHP, TypeScript, Python, Ruby, and now Golang using the APIMatic Code Generator.

We are excited to announce that our new Go SDK Code Generator is now available as an alpha release. According to the StackOverflow Developer Survey 2023, Go is used by ~14% of professional developers worldwide and is ranked amongst the top most admired languages by developers. Developers appreciate Go for its simplicity, speed, cross-compilation support, concurrency primitives, and expansive standard library. Go developers commonly use it to create distributed network applications, cloud-native services, and standalone tools and utilities. Using the new APIMatic Code Generator, API Providers can now make their APIs accessible to Go developers by generating strongly typed, idiomatic Go SDKs for their API.

In this blog, we will take a look at the design of the Go SDKs generated by APIMatic. We will especially focus on how they help improve the developer experience, reduce onboarding time, and simplify integration code for API developers. We will also check why APIMatic’s Code Generation solution, especially for Go, stands out among the various options for creating SDKs.

A Quick Tour of the Go SDK

Let’s check out what the new Go SDKs generated by APIMatic Code Generator look like. These examples are from an SDK generated for a model payment API we call IdealPay and help illustrate the Go SDK usage experience.

Making an API Call

The Go SDK wraps the API into a Go-native interface while hiding away all the nitty gritty details of making an API call. JSON request and response bodies become Go structs. API calls become method calls. Authentication and error handling are built into the SDK and require minimal effort on the part of the developer to use. All this adds up to a developer experience that reduces the need for the Go developer to go back and forth between the API reference and the code editor as they figure out how to integrate the API into their application.

Let's check out a code snippet that shows an API call being made using the Go SDK:

Walkthrough of making an API call using the Go SDK

APIMatic takes a batteries-included approach to the Go SDK design, reducing the effort needed by the API developers to write production-ready code by providing commonly used features such as:

  • Concurrency Support: The client is designed to be immutable. This allows the client instance to be shared between multiple threads without running into race conditions.
  • Timeout and Retries: The SDK is designed to be resilient. Intermittent API call failures are handled by retrying the API calls based on an exponential backup algorithm. Non-responsive HTTP calls are timed out safely to release resources.
  • Context-Aware Calls: The SDK allows the caller to pass “context”. This allows the SDK to be used in network applications where an API call might need to be canceled whenever a parent request is canceled.

Working with Request and Response Data

The generated Go SDK provides a strongly typed interface for making API calls by providing Go types for all API requests and responses. In the Go language, this means providing structs, enums, and interface types that help the developers provide the right data to the SDK when making API calls. The Go SDK then converts this data into the right API call by serializing the data as JSON, XML, or form data. However, the developers are oblivious to this detail as the SDK does the heavy lifting of creating the right API call saving the developer from having to read the API reference docs.

The code snippet below shows the request data being passed to the SDK during an API call. Check out how the Go SDK exposes a neat Go-native interface for handling various request data types:

Working with request data types in Go SDKSince the response data is also strongly typed, the Go developer can quickly introspect the response type using their IDE’s auto-complete or type-hint functionality. Check out how VS Code hints at the available properties in the PaymentLink response:

VS Code response type hinting

Strong typing in both request and response helps catch code errors early in the development process by restricting the data types that can be exchanged with the SDK. The compiler raises errors during development which helps the developer correct mistakes, thereby eliminating an entire class of bugs from reaching the production environment.

Documentation and Code Samples

APIMatic not only generates the Go SDK but also supports creating a complete SDK Reference documentation in the shape of a website. This website contains the following for Go SDK and other generated SDKs:

  • Installation and usage instructions for the SDK
  • Endpoint reference
  • Request and response type reference
  • ⭐ Code samples showing API calls using Go SDK
  • ⭐ API Console to make API calls without leaving the website

The screenshot below shows a reference documentation site that we have created for a Petstore API, showing documentation for the “Add Pet” endpoint using the Go SDK:

VS Code response type hintingDevelopers can copy the code samples from the documentation into their IDE to quickly integrate the API call into their application. Since these code samples use the Go SDK, they are DRY (Don’t repeat yourself) because they do not embed the entire API call implementation detail inside the code samples; that implementation along with the types needed for requests and responses are provided by the Go SDK.

While inside the IDE, developers benefit from the IDE “Intellisense” features which help surface the method, types, and documentation for the SDK. This helps speed up the build-and-test development loop for developers, improving developer experience:

VS Code showing documentation for types

Why Choose APIMatic’s Code Generator for Go SDKs?

APIMatic’s newest support for the Go language helps advance our goal of building the most comprehensive platform for crafting API developer experiences. With 8 years of development and millions of SDK downloads under its belt, APIMatic Code Generator represents the most mature solution for API providers to create SDKs for their API Programs.

Here’s why we think our newest Code Generator for Go SDKs stands out from the crowd:

  1. Designed from scratch for Go: APIMatic takes a principled approach to SDK design focusing on creating strongly typed, idiomatic SDKs that make the developers feel at home. Go developers will appreciate the attention to detail we have put into crafting neat types and interfaces in the SDK aligned with Go’s language conventions. This includes the use of the new Generics feature to simplify interfaces, the presence of doc blocks to types and methods, and the locking of dependencies using Go modules.
  2. Strong OpenAPI Coverage: APIMatic’s Code Generator has expansive support for OpenAPI features, including polymorphic inheritance, multipart requests containing files, nullable and optional types, and authentication schemes such as OAuth 2. Our API Validator helps you get the most out of your OpenAPI definition by finding common issues including hard-to-detect semantic errors.
  3. Zero-maintenance SDKs: APIMatic’s approach to SDK generation helps significantly reduce the cost of ownership of SDKs and docs for API providers. Once you’ve published your SDKs, APIMatic will automatically provide updates and security fixes via the Core Libraries that power our SDKs. Add APIMatic’s documentation solution and you have API and SDK references that stay up-to-date with your latest API definition changes.

Just like this exciting new release, you can always depend on the APIMatic team to deliver awesome improvements to the SDKs and supporting API tools. Our recent releases include:

  • Complete overhaul of the core functionality of SDKs resulting in leaner code and easier maintenance.
  • New documentation for Code Generation Settings to help you discover all the ways you can customize your SDKs.
  • Coming soon: Expanding support for complex OpenAPI schemas like OneOf and AnyOf.
  • Coming soon: Ability to fix OpenAPI definitions automatically.

So what are you waiting for? Ready, set, Golang! 🎉

You can sign up for a free 14-day trial of APIMatic to generate a Go SDK for your API. During the trial, you can generate SDKs and API Documentation in all programming languages supported by the APIMatic platform.

47