DEV Community: APIMatic.io

API Docs-Bots, Assistants & OpenAPI Auto Fixing

APIMatic.io — Thu, 04 Apr 2024 22:27:37 +0000

Let's look into our crystal ball to see how Docs-Bots, API assistants, and OpenAPI auto-fixing will drive future API adoption.

2024 marks the first decade of APIMatic incorporation. That’s quite a lot of time being part of this beautiful community of API developer tools and witnessing the API industry evolve. From new API description formats popping up to old ones fading away, from the love of HATEOAS to the rise and fall of microservices, the GraphQL storm, some big acquisitions, and a few sad exits, tech alliances, patent fights, standardization efforts - it’s been an exciting rollercoaster!

Where will the industry be heading in the future? From the learnings of a company focused on improving the developer experience of both API providers and consumers, we pick three active areas of innovation:

1- API Docs-Bots to Massively Reduce Developers’ Onboarding Time

API documentation solutions have come a long way in the past few years. Features like runnable code samples and guided walkthroughs help developers get up and running quickly with an API. Still, a learning curve is involved before a developer can start writing the integration code.

Generative AI will likely replace the learning curve and long API onboarding steps in the future. For example, instead of going through each endpoint, reading the docs, and writing the code for authentication flow, a developer can ask a query to an “API Docs-Bot” in natural language and get the integration code for the desired use case in a few seconds.

What About Code Reliability?

At the moment, Gen-AI is good at generating syntactically correct code, but it lacks an understanding of the semantics. Therefore, a challenge would be training the AI bot to generate production-ready integration code for different scenarios. A couple of ways to solve this problem are using:

An expert developer: to feed detailed prompts to GenAI and keep refining until the integration code of a desired quality level is returned. It is manual and hard to scale.
A sophisticated code generator for APIs: to train the AI on the SDK of an API so that its responses are based on deterministically produced code by the code generator.

To test solution # 2, we’ve conducted a few experiments using APIMatic, and the initial results of creating an API Docs-Bot by combining the two machines have been quite promising (see below). Expect to see similar attempts in 2024 by API solution providers.

2- AI Assistants to let Non-Developers Play with APIs

Developers or non-developers, we all use APIs. The difference is that developers build apps using APIs, while non-developers use APIs via those apps. Moreover, developers can use an API for countless use-cases, while non-developers can only try limited use-cases built in an app by a developer.

Imagine, I want to know how many times I have been to restaurants in the past 12 months, the total expense, and the average cost per visit. Today, my options are:

to download and look manually into my bank statements or
find a FinTech app which offers this functionality, or
get a developer to write an app using OpenBanking APIs. Later, what if I want to see my top expense categories for the last two years as a graph? Again, I can do it manually or depending on the functionality built by a developer.

The good news is that Gen-AI can remove this dependency, i.e., letting non-developers access an API the way they want without needing a developer in the middle using AI assistants. Because of its conversational nature, the end users can easily provide their input in natural language and further refine the output conversationally if needed.

In 2024, we expect to see a plethora of AI assistants. However, similar to the API Docs-Bot case, training Gen-AI to reliably access data from an API and convert that into information takes a considerable amount of time. A quicker way would again be to use a code generator to reliably and instantly get the integration code and train the AI to process the data coming through the APIs.

We experimentally built a financial assistant during the recent holidays using Payments New Zealand’s OpenBanking APIs. Here are a couple of queries in the screenshot below to depict the outcome (the sandbox data has been expanded to try different scenarios):

3- Governance - from OpenAPI Ratings to OpenAPI Fixing

As the significance of API governance and design continues to grow, we see some new tools arriving in the market, focusing on assessing an API's quality through its API definition. Two noteworthy examples include Zuplo's Rate My API and Trebble's API Insights. Both tools audit API definitions against certain standards/conventions and assign them a good/bad score for various categories, including design, security, completeness, and more. By highlighting specific areas of improvement, these tools empower API designers to make their definitions flawless. At APIMatic, we also help API designers improve their definitions for stronger SDK and documentation generation. Following is what an auto-generated audit snapshot of an OpenAPI file with some validation and linting issues usually looks like:

Why is a Flawless API Definition Important?

GIGO (Garbage In, Garbage Out) is a familiar slang in the computer science world, meaning a flawed input would produce a nonsense output. GIGO is perfectly applicable to the processes that need OpenAPI definitions as input. If you're looking to feed your OpenAPI definition to GenAI, want to generate Docs, SDKs, or do anything else, you need to ensure a flawless API definition or don’t mind piling up some garbage. This problem is not new for API definition files (see some common mistakes from 2018 in OpenAPI, APIBlueprint, and RAML definitions), but it is growing in magnitude and demands immediate attention. Based on APIMatic users, we saw:

20% of the total OpenAPI definitions brought to APIMatic violated OpenAPI standards and failed during the import process, whereas
50% conformed to OpenAPI standards but lacked the elements required to generate viable integration code.

Towards a Future of Auto-Fixing

While an audit report helps identify the issues, somebody still has to fix those problems. This is the hard part due to the time and resources required to rectify a complex OpenAPI definition, especially if one is not too familiar with the syntax. Can AI help with the auto-fixing? Yes, but reliability will remain a question unless somebody pays to train like an LLM. Till then, OpenAPI experts or man-made machines with pre-defined rules will keep on helping the API designers.

Therefore, in 2024, we expect to see the audit tools moving forward and help designers with (semi) automatically fixing the issues. At APIMatic, we’re running a “Fix My OpenAPI” movement primarily focused on SDK and Docs generation. A free-to-use VS Code extension comes with over 1200 predefined out-of-the-box rules. It ensures strict adherence to API standards and recommends improvements and best practices to enhance one’s API definition. Moreover, the extension has an “auto-fix” feature to help remove some pesky issues with just a few clicks.

That’s it for today. Let’s see what new and improved tooling 2024 brings up to help API designers while they curate OpenAPI definitions and how far the Generative-AI wave takes the API space. Feel free to reach out at adeel@apimatic.io for any feedback or if you want to try out the Gen-AI POCs mentioned in this blog. I also want to acknowledge team APIMatic, especially Saeed, Ali, Faria, and Sidney, for their valuable input and R&D initiatives.

APIMatic SDKs in Backstage Developer Portal

APIMatic.io — Wed, 06 Mar 2024 01:59:37 +0000

By combining APIMatic’s high-quality idiomatic SDKs with the Backstage developer portal, you can create a compelling and differentiated developer experience.

What is Backstage?

Backstage is an open-source platform developed by Spotify for managing the entire lifecycle of developer infrastructure, including services, APIs, documentation, and more. Backstage streamlines the development process through its centralized and customizable platform, offering a unified dashboard that consolidates information on projects, services, and infrastructure. Acting as a service catalog enhances transparency by allowing teams to document and discover internal services easily. Backstage's extensible architecture supports a robust plugin ecosystem, enabling teams to tailor the platform to their specific workflows and preferences. The platform promotes collaboration, accelerates onboarding through standardized documentation, and integrates seamlessly with various DevOps tools.

Extending Backstage with SDKs

As the number of services and API complexity grows, teams using Backstage as their developer portal may look to add SDKs to support developers in multiple languages. SDKs include code libraries, documentation, getting-started guides, and code samples, empowering developers to interact seamlessly with APIs and services.

APIMatic automates the creation and maintenance of SDKs in various programming languages. In this tutorial, we’ll show you how to take your API developer experience to the next level by using APIMatic to generate SDKs and incorporate them into your Backstage portal.

APIMatic goes above and beyond to ensure a good developer experience by providing auto-generated SDKs in the programming languages you need and includes SDK documentation with guided walkthroughs, code samples, and getting started guides.

We can integrate APIMatic SDKs by incorporating them into a dedicated SDKs page within existing documentation or by embedding the SDKs documentation as a newly registered component in the Backstage portal. In the upcoming sections, we will explore both options to see how they can improve the developer experience within the backstage portal.

Generate SDKs and Documentation with APIMatic

In this section, we walk through publishing an API portal for APIMatic SDKs. If you already have a generated portal with APIMatic, skip to Integrate APIMatic with Backstage section.

Start your free trial with access to all SDK generation features.

Import an API definition

Follow these instructions to import your existing API definition or use the example Petstore API.

Generate SDK Portal

Follow these instructions to generate a portal for your SDKs using the API definition you just imported. In the last step, you’ll click “Preview API Portal”. A preview of the default landing page of your portal opens up in a new tab on your browser. From here onwards, you can customize your portal's look, feel, and behavior or publish it.

Publish SDK Portal

Click the Publish Portal button at the bottom of the page and follow these instructions to publish a hosted portal.

Once publishing is complete, visit your unique URL to view your SDK documentation. You can also find the URL in the portal Settings > Publishing section of the portal editor.

Integrate APIMatic with Backstage

Note: This guide assumes you already have an API Documentation portal with Backstage. For more details, visit their site.

Create a custom page for SDKs

When completed, your Backstage developer portal will include a custom SDK page.

After setting up the Backstage platform by following their getting started guide you’ll see your instance running at http://localhost:3000/. Before running the application, ensure that the tech docs configuration section in
app-config.yaml is configured to run locally.

The first step is to create a customized page in the Backstage platform. The page will include a list of all the supported language SDKs and links to setup instructions.

For an overview on the docs-like code solution provided by Backstage, which is responsible for rendering documentation via markdown files, consult the TechDocs documentation.
Create a markdown file in your application’s doc folder, which you’ll find at <root folder/docs>, and provide a descriptive name <doc name>.md.
We’ve created a markdown template. Copy the markdown from here and paste it into your markdown file. Note the text is for our Petstore example, so you can customize the text for your API. You must replace the YOUR_DOCS_SLUG and YOUR_API_KEY placeholders with the actual values for your SDK documentation. Detailed instructions are below.
YOUR_URL_SLUG represents the slug you defined when publishing your APIMatic Portal. To locate this value, hover over the top left corner of your API definition tile in the APIMatic Dashboard and copy the link. You will just need the subdomain of this URL e.g. https://YOUR_DOCS_SLUG.apimatic.dev. Replace all instances of YOUR_DOCS_SLUG with this value.

5.YOUR_API_KEY represents a unique identifier for your SDK documentation. To access the API Key for your SDK documentation, click the kebab menu (three vertical dots) on the API definition tile to retrieve the API integration key.

From the context menu, select ‘API Integration Keys’.

Copy the property titled API KEY. In the markdown template, replace all instances of YOUR_API_KEY with this value.

This concludes your setup for this custom page. Your new page lists all your SDKs. You can save your changes and proceed to the next step.

Create a link to the custom SDK page

Create a mkdocs.yaml file in your application’s root folder and change it to reference the markdown document in the navigation bar.

After running the application successfully, select Create from the navigation bar and press the REGISTER AN EXISTING COMPONENT button.

Import the catalog-info.yaml file and analyze it on the next page. The catalog-info.yaml file analysis will reveal any problems. Please take care of them before proceeding. You can read more about it here.
Provided the previous steps executed smoothly, you will see the VIEW THE COMPONENT button. Pressing this button takes you to a page with the newly created component details. Click on the DOCS tab to view the linked SDK documentation.

Embed APIMatic’s SDK Documentation in Backstage (Optional)

This section is optional because your SDK documentation is already published and publicly accessible; embedding it in your Backstage portal is a nice touch but not a requirement.

In the previous section, we created a page that redirects to the SDK documentation hosted by APIMatic. We can go further and embed the SDK documentation inside a Backstage portal, and it would look like the following.

Generate an APIMatic embed script

APIMatic’s SDK Documentation can be embedded in any web page via an embeddable script. To generate the embed script for your APIMatic docs:

Navigate to the APIMatic dashboard.
Locate your API definition tile.
Click Edit Docs to navigate to the Portal Editor.
In the top left corner of the Portal Editor, click the ‘Publish Portal’ button.
Choose the Update Embedded option on the next screen.
Select the API version you want to generate the embed script for and click Generate Script.
You will be presented with a snippet containing the script. You need to copy this entire script to use in the next section.

Add Embed Script to Backstage Portal

In the previous steps, we used APIMatic to create an embed script. Now include it in the Backstage portal.

First, we’ll create a customized page called SDKs that is accessible from the portal's landing page. This new page displays our embedded portal links to the SDKs.

To achieve this please follow the instructions given in the Backstage official documentation of customizing the home page.

We are modifying the default behavior of the application’s home page to link the SDK documentation. Create a new file HomePage.tsx. This is where our new homepage component will live. It will look like the following:

Now create a component with the name ApimaticWidget.tsx in the components folder of the Backstage application apps folder. This component will load the embedded portal by calling the initializeWidget method. The method uses the script copied earlier in the previous section.

To make the portal accessible through an engaging information card, we will create another component with the name InformationCard.tsx.

Finally, let's add the routes to the ApimaticWidget component in App.tsx to make the customized SDK page accessible from the navigation bar.

Now we have achieved an interactive and convenient way of making the SDKs even more accessible for the developers.

Clicking on Petstore SDKs takes us right to an embedded APIMatic Portal without leaving our Backstage developer portal.

What’s Next?

In the ever-changing landscape of API-driven development, combining Backstage's API management capabilities with APIMatic's automated SDK generation makes it easy for organizations to establish a strong foundation for API development and consumption.

If you liked what you saw in this blog, Sign up for APIMatic and get started! We would love to see what you build with APIMatic. Tweet your updated Backstage Portals to us at @APIMatic or drop a mention on Linkedin.

Build Go SDKs for your API

APIMatic.io — Thu, 25 Jan 2024 14:42:00 +0000

We’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:

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:

Since 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:

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:

Developers 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:

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:

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.
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.
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.
Integration guide for Readme users to add SDKs to their documentation sites.
A community for SDK creators and developers to learn best practices for building 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.

Rev Your Engines: The SDK Generation Race is About to Begin!

APIMatic.io — Mon, 22 Jan 2024 14:28:00 +0000

Hey, speed demons and code maestros! 🚀 Buckle up for an adrenaline-fueled race through the SDK generation landscape featuring the contenders: APIMatic, Speakeasy, and OpenAPI Generator. As a seasoned SDK builder in the API realm, I'm taking these powerhouses for a spin to determine which emerges as the ultimate champion.

Today’s Race Schedule

Pit Stop 1: Validation and Linting
Building the Car: Code Generation
Starting Line: Code Compilation
Test Drive: Code Evaluation
Victory Lap: Documentation

So, fellow code warriors, fasten your seatbelts and join me. Let's determine which contender will take home the coveted checkered flag in this epic battle of code prowess! 🏁

Disclaimer:

Some modifications were made to Lob’s OpenAPI definition to prepare for our race. We removed properties that are beta and premium and modified property values that are unique to a specific account, i.e., an ID for an existing object (template, address, etc.). This is advice we would provide a company to create runnable code snippets for all users. The modified version of Lob's OpenAPI definition we used is available here.

APIMatic
We found two idempotency keys defined with similar names, Idempotency-Key and idempdency_key, resulting in a duplicate variable. We removed one of the idempotency_key parameters.

Speakeasy
Three arrays did not have the items attribute defined, so we corrected that and removed a script tag that blocked our test.

OpenAPI Generator
The merge_variables default value broke code generation, so we corrected this in our API definition.

You can put your API definition to the test with APIMatic.

Start your free APIMatic trial today!

Pit Stop 1: Validation and Linting

In the world of SDK racing, precision is key. Before we hit the track, we're making a pit stop for validation and linting. Which SDK ensures a clean and error-free journey, smoothly navigating Lob's API definition with its oneOf, allOf, and anyOf twists and turns? Let's kick off the race by inspecting their linting and validation prowess.

OpenAPI Generator

In testing OpenAPI Generator, I found the validate command wasn’t very useful in surfacing issues. I recommend running the generate command to receive more complete linting and validation. The warnings centered on correcting reserved words, ignoring maxLength, pattern validation, and examples on the requestBody while acknowledging limitations around allOf support. Sadly, the warnings lack line information or suggestions to address these warnings.

Speakeasy

Speakeasy also provides a CLI with a validate command that works better than OpenAPI Generator. Their validation results are more readable with line information. Unfortunately, no suggestions for fixing issues are provided. I also received a warning: “X is potentially unused or has been orphaned.” My investigation found these warnings to be false positives.

APIMatic

APIMatic’s validation provides actionable feedback for your API definition to improve code quality.

Each warning includes details and links to documentation about the violation with suggestions for fixing it.

2. Building the Car: Code Generation

Once the engine is finely tuned, it's time to build the race car. Code generation is our assembly line, where APIMatic, Speakeasy, and OpenAPI Generator vie for the title of the most reliable pit crew. Who constructs the SDK with the precision of a seasoned mechanic? Let's tighten those bolts and see which one builds the meanest machine.

Comparing SDK code generators in every language can be time-consuming. I’ve found from experience that strongly typed languages like C# and Java are suitable for uncovering issues other languages may let slip by. For this reason, I chose Java to compare the three generators.

SDK generators will let you pass if your OpenAPI definition is syntactically correct. You can generate code, but you’ll also see warnings that some aspects of your API definition could be problematic. To assist you, code generators will remove or ignore things in your API definition that may interfere with successfully generating code.

Why do SDK code generators allow you to proceed? It’s a choice that allows you to experience the tool and examine the output without requiring you to spend hours resolving warnings of varying severity.

Will you want to optimize your API definition before publishing your SDKs? Yes, and APIMatic’s VSCode extension with 1200 rules specifically around code generation is an excellent tool for the job.

For those still in the evaluation phase, don’t spend too much time optimizing your API definition, as each code generator enforces slightly different rules; you’ll go crazy trying to please them all.

Using Lob’s API definition, I successfully generated Java SDKs using each tool. 🎉

Speakeasy did have the following warnings during code generation.

The component is potentially unused or has been orphaned.
Only enum types of string or integer are supported. Enum type won't be generated and will be treated as base type
Enum is nullable but does not contain a null value
anyOf should only contain types which are compatible with each other, use oneOf if the response can only match one type at a time
anyOf will not be supported by Speakeasy, treating as oneOf
missing schema type for X component, but found properties treating as object

3. Starting Line: Code Compilation

Engines roar as we move to the starting line. Code compilation is the moment we ignite the fuel and unleash the horsepower. Which SDK delivers a seamless start, ensuring the code compiles with the precision of a pit crew orchestrating a Formula 1 pit stop? The contenders are revved up, and it's time to hit the track.

APIMatic compiled successfully without any errors or warnings. Unfortunately, both Speakeasy and OpenAPI generators generated SDKs that failed to compile with 32 and 100+ errors, respectively.

To keep the race going, I got behind Speakeasy’s car and pushed it. From my previous experiment, I found inline headers in the Petstore API broke Speakeasy, so I removed all referenced headers in Lob. To my surprise, the generated Java code with Speakeasy compiled.

Note: removing API features is not recommended, but it was necessary to continue our race.

Sadly, I couldn’t get OpenAPI generator past the failed compilation.

4. Test Drive: Code Evaluation

The rubber meets the road as we take the remaining SDKs for a test drive. Navigating Lob's API definition is our challenging course, filled with oneOf, allOf, and anyOf curves. How well do our contenders handle the heat? We're evaluating the experience of using these SDKs. Can we make that first API call, and is the code idiomatic?

For this comparison, I created a sample application for APIMatic and Speakeasy to retrieve a list of addresses and print the address's street, city, and zip code.

APIMatic

I copied and pasted the code sample from the documentation into my IDE to retrieve a list of addresses. The code ran successfully and retrieved a list of addresses, which was a good sign. The addresses returned can be one of two types: a US or an international one. These models have slightly different properties. For example, the US has zip codes while International addresses don’t. APIMatic’s Java SDK has an address container class with a match method to handle this. Using the match method, I can determine the address type and then access the corresponding data using getters and setters, which is the idiomatic way to interact with models in Java.

Speakeasy

I copied and pasted the provided code sample for the list addresses endpoint from the ReadMe. Running the code, I didn’t receive a list of addresses but a 422 status code. It turns out the code sample provided included malformed parameters. Once I figured out the cause of my 422, I removed the optional parameters and successfully retrieved a list of addresses.

The address list response uses a generic object to hold the data. Because the data structure is unknown, I utilized a JSON tree structure to traverse and access address details. While the resulting code works, it is a suboptimal experience for Java developers.

OpenAPI Generator failed to compile and, therefore, was not included in the test drive.

5. Victory Lap: Documentation

As we approach the finish line, documentation becomes our victory lap. Clear, concise, and user-friendly documentation is like a well-designed pit board guiding you to SDK mastery. APIMatic, Speakeasy, and OpenAPI Generator boast top-notch documentation, but who provides the smoothest ride toward victory? The final stretch is where we evaluate their documentation to determine the true champion of this high-speed SDK race.

What type of documentation do I include in my comparison? Any docs generated to support the SDK code library, including a getting started guide, SDK reference, code samples, and use case guides.

OpenAPI Generator

A ReadMe markdown file is generated with installation information for both Maven and Gradle and a complete code sample as a getting-started guide. The SDK reference generated is a collection of markdown files. That includes the following for each endpoint:

Parameters
Return type
Authorization
HTTP request headers
HTTP response details
Complete code sample

OpenAPI Generator’s code samples look runnable, but I noticed the create methods would fail as new objects don’t set any initial values.

Speakeasy

Speakeasy’s ReadMe only provides Gradle install instructions. A complete code sample is provided as a getting started. The Speakeasy SDK reference is a collection of markdown files and provides fewer details than the OpenAPI Generator.

Parameters
Response
Code Sample

The code samples included in the SDK reference are complete files with import statements. Like OpenAPI Generator, the code samples look runnable, but when testing the listAddress method, the default parameters resulted in a 422 status code.

APIMatic

APIMatic’s ReadMe is similar to OpenAPI Generator and Speakeasy, focusing on installing and getting started using the code library. A big difference is the build and installation instructions walk a developer through setting up a sample Eclipse project with the SDK as a dependency.

In addition to a ReadMe, APIMatic provides a hosted developer portal. The portal includes API reference docs and an SDK reference for each language. It’s easy to navigate and explore the methods, models, enums, and exceptions supported by the SDK.

The developer portal includes interactive documentation. Modifying property values in the docs update code samples in real-time. You can make live API calls from the documentation, similar to a Postman collection. Lastly, code samples default to a condensed display, but through the config settings, can show a complete runnable code sample. While testing the code sample address list, it ran as expected.

Conclusion

In the thrilling race through the SDK generation landscape, we pushed APIMatic, Speakeasy, and OpenAPI Generator to their limits, exploring validation, code generation, compilation, test drive, and documentation. The checkered flag has been waved, and after navigating the twists and turns of Lob's API definition, APIMatic emerges as the undisputed winner of our high-speed showdown.

Final Scorecard

To further validate our findings around code generation and compilation, we put ten additional API definitions through these three SDK generators, and the results are below. The yellow warning symbol means there were problems with the languages listed.

It’s time to put your API definition to the test with APIMatic.

Start your free APIMatic trial!

Your 2-week trial gives you access to all features to test the platform’s SDK generation capabilities.

New OpenAPI VSCode ext. to Validate, Lint, and Auto-Fix

APIMatic.io — Mon, 15 Jan 2024 14:27:00 +0000

At APIMatic, we process hundreds of thousands of API definitions every year to transform specification formats and generate SDKs and Docs. Interestingly, a big chunk of those API definitions is syntactically correct, but not good enough to generate highly quality code. This is simply because OpenAPI and other popular API specification formats are not built with code generation in mind. We are thrilled to announce the release of our new VS Code extension which comes equipped with over 1200 pre-defined rules to help you effortlessly validate, lint, and auto-fix your API definition files and generate powerful SDKs and documentation.

In this blog, we will discuss in detail why we built this extension in the first place and how it can help you in your API journey. Or if you're eager to get started with the extension, here's the download link:

Download from the Visual Studio Marketplace

Another Validator! But Why?

This has been the most common question we’ve received so far. There are some great tools in the market, but they have a few shortcomings that make them less ideal for users focused on auto-generating SDKs from their API definitions. Those shortcomings include:

No dedicated rulesets for code generation

While the existing tools, such as Spectral, have some basic rulesets and plenty of third-party rulesets available in their platform, they do not provide any rulesets out of the box to validate API specifications for code generation purposes.

No enforcement of mandatory standard checks

API specification standards like OpenAPI make some rules mandatory using the MUST/REQUIRED keywords. Some of those rules are quite important, but, unfortunately, not all of them are enforced by available tools, possibly to provide greater flexibility.

Here’s one that disallows keys of reusable components from having anything other than alpha-numeric characters, dashes, periods, and underscores in them:

These keys/names play an important role when generating code. However, I’m able to easily get away with any character in my schema name without any related error/warning in Spectral:

Too much flexibility

All validators including Spectral offer the ability to disable rules as required. In some scenarios, flexibility can be a good thing. But when it comes to generating code, knowing beforehand what rules can negatively affect your output if disabled, can be hard to determine and so this flexibility can be a double-edged sword. You can even end up disabling something important.

Missing documentation

Nothing is worse than running into a tricky issue and not having any documentation to help you understand it. Here’s an example of Spectral where documentation is unavailable for some of its messages:

No contextual information for an issue

Sometimes an issue’s message alone cannot convey enough information, especially when it is important to understand “how” that particular issue originated in the first place. None of the existing tools provide any extra information along with its messages.

No support for auto-fixing common issues

Several common issues (e.g. inline schemas) often just need simple removal or relocation of certain components in the API definition. Auto-fixing can in such cases greatly reduce the time it takes to bring the API definition to the final shape. Unfortunately, existing tools still lack advanced features like these.

Lack of merge-aware validation

API providers looking to release their microservices as a single unified service for consumers require merging their API definitions into one. Ensuring each API definition is valid before and after the merge is a crucial phase that is not supported by any of the tools out there.

No support for REST formats other than OpenAPI

Most validators like Spectral focus only on OpenAPI as it is the most popular and widely adopted API specification format. However, we’ve observed that other API specification formats are still in use even if in the minority e.g. RAML, Postman Collections, API Blueprint, WADL, etc. These formats are not supported by any of the popular validators out there.

Validation Reimagined - Diving deeper into APIMatic VS Code Extension

1 - Familiar UI

Visual Studio Code is a platform that millions of developers are already comfortable with. APIMatic’s extension has been built with simplicity and efficiency in mind. It offers you dedicated views in the same familiar environment so you can quickly get started.

2 - Compliance with API specification standards

We enforce all checks marked as mandatory by specification standards like OpenAPI. Such checks are also not configurable. This ensures that your API definition is not only compatible with APIMatic and its products but will work well with other tooling out there as well.

In total, we offer 739 validation rules to check compliance, with 329 rules targeting only OpenAPI definitions.

3 - Out-of-the-box lint checks for code generation and general quality

To ensure smoother SDK generation, DX portal generation, and API specification format transformation, we lint your API definitions against 542 out-of-the-box lint rules with 503 targeting OpenAPI definitions alone. These checks cover all common issues including prevention of inline schemas, ensuring better naming conventions, etc.

You can easily configure the lint process as per needs e.g. you can skip certain rules or even entire rulesets, override the default severity of the rules, and even add custom lint rules.

4 - Support for auto-fixing common issues

This being one of the unique offerings, our auto-fix feature in the extension lets you remove some pesky issues with just a few clicks:

As I mentioned earlier, OpenAPI and other formats aren’t designed for code generation. One of the most common issues we see because of this is an abundance of inline anonymous schemas in API definitions that negatively impact SDK and DX portal generation. Most users we encounter who have such definitions are not always familiar with ways to tackle them efficiently. With auto-fixing, we aim to ease their workload by handling such fixes directly in their files, ensuring accuracy and preventing additional issues. This way they can focus on what matters.

5 - Richer validation experience

In addition to the basic validation support of showing messages in the Editor and Problems view, our extension also provides dedicated views that enhance your validation experience. These views offer improved issue comprehension and quicker access to the information you need, enabling you to address issues with greater efficiency.

Validation Summary View - Get a birds-eye view of all issues

This is a view that shows a complete overview of the validation status of your workspace.

From here you can:

Navigate easily through all validation messages which are grouped intelligently based on severity and whether they are validation or linting messages. Inside these groups, all messages targeting the same issue are grouped, aiding you in addressing all instances of the same issue before moving on to the next. This helps improve the overall efficiency.
Generate reports in multiple formats (PDF, HTML, Markdown, JSON) for your external stakeholders.
View an overall score of your API workspace which roughly predicts how good or bad the output that you generate from this API definition is going to be.

Current Position Issues View - See in-depth context for all issues you are currently working with

See the in-depth context for all issues you are currently working with.

This view helps show more context for all issues applicable at the current cursor position in the Editor. The information shown in this view includes:

Issue message.
Severity of issue.
The exact location of the issue in the file with the complete line number and position range.
A breadcrumb or JSON reference path to the component.
Key-value pairs containing contextual metadata to help understand how and why the issue originated.
A reference call tree that shows a nested list of components referencing the current component to help understand how the issue originated.

Learn More View - Understand what an issue means and its resolution

Developers are all too familiar with issues that leave them scratching their heads in confusion. We understand that time is precious so we allow you to view details of an issue from within the extension in the Learn More view:

This includes a detailed description of the issue to help you understand what the issue means and why it occurred as well as hints that can be followed for resolving it. We also list down all relevant external links that can be used to learn more about the issue if needed and much more.

6 - Merge-aware validation

APIMatic supports merging multiple API definitions. To ensure a successful merge, it is required that each API definition involved is valid before and after the merge. This is a multi-layer validation process and is supported by our VS Code extension as well.

7 - Multiple API specification formats supported

The extension not only supports OpenAPI definitions but also has basic validation support for other API description formats including RAML, API Blueprint, WADL, WSDL, Postman Collections, Insomnia, HAR, etc.

8 - Ability to transform API specification format

The extension comes with built-in support for API Transformer allowing you to effortlessly convert your API workspace to your chosen output format. For instance, you can convert from OpenAPI to Postman and more.

9 - Better support for APIMatic users

If you are already an APIMatic user, we let you build your API definition from within the extension to check if the API can be successfully exported into APIMatic. Once the API definition is ready, you can easily export it to your APIMatic Dashboard for SDK/DX portal generation without needing to leave the VS Code extension. The extension offers minimal version management as well by letting you replace an existing version or add new versions to the same API group entity.

To configure APIMatic processes, you can easily add an APIMatic Metadata file with just a few clicks:

We support validating all APIMatic-specific files including custom rulesets, APIMatic Metadata files, etc. so you can avoid any common mistakes.

What’s next?

The VS Code extension is currently available in preview mode for our APIMatic users. We welcome you to try it out now:

Download from the Visual Studio Marketplace

You can learn more about each of the extension features here and share any feedback.

Anticipated future changes include, but are not limited to:

Support for generating SDKs in one or more languages from within the extension.
Support for publishing a DX portal from within the extension.
Improvements to stability.

Enhance Redocly with SDKs from APIMatic

APIMatic.io — Fri, 12 Jan 2024 20:31:20 +0000

Redocly is a popular developer documentation platform with support for a developer portal and API docs with a developer-friendly workflow for creating and maintaining documentation. In this article, we’ll focus on how to extend Redocly’s API Docs tool by incorporating SDKs generated by APIMatic.

At APIMatic, we generate strongly typed SDKs along with language-specific documentation and code samples, all built from OpenAPI definitions.

In this post, we’ll look at how APIMatic-generated SDKs can be embedded into Redocly’s API Reference solution to elevate the API Integration experience for your developers. This screenshot shows what we are going to build in this tutorial:

This article assumes you have already signed up to Redocly, set up your GitHub repository, connected it to Redocly’s API registry and added your API definition to the registry. If not then follow the Redocly API registry quickstart guide.

Generate SDKs and documentation

It’s easy to get started with APIMatic, just follow the steps below. If you already have a generated portal with APIMatic, skip to the next section.

Sign up for your APIMatic account.
Follow these steps to Import your API definition.
Once imported, click the Generate button and then click Proceed.
This will open a window. Click on the Preview API Portal.
You will be redirected to a new window to preview your generated SDK documentation

Publish your SDK documentation

Next, publish your SDK documentation so it is publicly accessible. Click the Customize button on the banner that appears at the bottom of your screen.

Click on the Publish Portal button on the top right of the Portal Editor.
You will be prompted to select a hosted or embedded portal. Select the Hosted option.
Select the API version for which you want to publish this documentation and click Next.
You need to provide a slug where this documentation will be hosted. The slug can contain one or more words separated by a dash “–“. Provide a unique slug in the textbox and click the Save & Next button.
With your unique URL set up, click the Publish button to initiate the publishing process. You’ll receive an email notification as soon as the process is complete.
Once publishing is complete, visit your unique URL to view your SDK documentation. You can also find the URL in the portal Settings > Publishing section of the portal editor.

SDKs in your Redocly API Docs

Let’s insert APIMatic SDKs into your Redocly API docs.

Redocly API docs render the main description of an API definition as a separate section. We will leverage this capability to create an SDK section at the beginning of our API Docs.

Open your Redocly Source Directory and navigate to your OpenAPI Description file. If you used the sample GitHub Repository provided by Redocly, this should be the openapi/openapi.yaml file.

Find the info -> description property and determine if the value is provided inline or contains a $ref link to a separate markdown file. In the case of the latter, you can skip down to use our API description template.

Create a new markdown page in your repository named api-description.md inside the openapi/ directory.

Copy the info -> description value from the OpenAPI spec file and paste it into the newly created api-description.md file to retain the original description.

Now update the info -> description property in the OpenAPI spec by adding a $ref property to it with the correct path to the api-description.md file as shown in the screenshot below.

API Description Template

We’ve created a markdown template to help you add your APIMatic SDKs to your Redocly API Docs. Copy the contents of the template from here and paste them inside the api-description.md file after your original description text.

Customize API Description Markdown

You will now need to replace the YOUR DOCS SLUG and YOUR API KEY placeholders with the actual values for your SDK documentation.

Detailed instructions for doing this are listed below:

YOUR_DOCS_SLUG represents a part of the URL where your APIMatic Portal is published. To retrieve this value, hover over the top left corner of your API definition tile in the APIMatic Dashboard and copy the link that appears. You will just need the last section of this URL e.g. https://www.apimatic.io/apidocs/YOUR_DOCS_SLUG. Replace all instances of YOUR_DOCS_SLUG in the api-description.md file with this value.

YOUR API KEY represents a unique identifier for your SDK documentation. In order to access the API Key for your SDK documentation, click the kebab menu (three vertical dots) on the API definition tile to retrieve the API integration key.

From the context menu, select API Integration Keys.
Copy the property titled API KEY. In the api-description.md file, replace all instances of YOUR API KEY with this value.

This concludes the steps required to add an SDK section to your API Documentation. Commit your changes and push them to GitHub.

Redocly will automatically build the API docs based on your changes. Once the build process is complete, you can view the API docs and see the published changes.

🎉 Congratulations, you have successfully embedded APIMatic SDKs inside your Redocly API Docs.

Conclusion

The foundation of a good API program is documentation. As your developer audience expands, the need for an SDK program becomes a priority. It’s great to have flexibility when choosing from an array of tools to build your overall developer experience.

APIMatic provides an extensible code generation solution that works with virtually every documentation solution on the market. If you’ve liked what you read, sign up for a free 14-day trial of APIMatic and get started!

We would love to see what you build. Tweet your updated Redocly docs to us at @APIMatic or drop a mention on Linkedin.

Introducing the Art of Developer Experience Podcast

APIMatic.io — Tue, 23 May 2023 01:29:00 +0000

What the heck is “Developer Experience in 2023?” This is one of the questions we ask our guests (of course more politely) to see what they think. It’s a fairly new term and one with competing definitions depending on the group using it.

Our guests are from leading technology companies and they join me, Sid Maestre, to have authentic conversations about the challenges of creating products for a technical audience (often APIs) and discuss how DX is evolving. We dive into topics like API design, documentation, SDKs, tooling, developer relations, dashboards, metrics, and more.

We hope to spark ideas for ways you can improve the developer experience at your company.

Listen on popular Podcast platforms

In our first episode we ask Richard Fortune who spent the better part of a decade working on Xero’s developer platform what is developer experience.

When I join a new organization or introduce someone to an organization, they often have a lot of questions around what developer experience is. If you Google it, you’ll find it defined as UX for developers, but I think it’s a bit blurrier than that in the real world.

For me, developer experience is all about the journeys that people take when trying to connect to systems. As someone who has worked on the platform side repeatedly, I think it’s important to make that journey as easy as possible to help developers achieve success quickly. It’s important to consider what role they are playing when they’re building with you on that particular day, and that’s a really important first step. If you do that well enough on the first cut, it’s important to do it repeatedly on all the other stages of the journey. This really works well when you have additional offerings later on as well.

In episode two, Brian Rinaldi from Launch Darkly shares his thoughts on the term developer experience.

I completely agree that developer experience is a broad and vague term and it varies from company to company. At LaunchDarkly, my focus as a developer experience engineer is to make it easier for developers to onboard and use our product. This includes providing resources and tools to help streamline the process and improve the learning curve. Documentation is a significant aspect of developer experience, and I contribute to our docs even though we have a dedicated docs team. While some companies may focus more on developing tools to ease the onboarding process, my role is more content-focused.

We chatted with Luke Kilpatrick in episode three and addressed the elephant in the room with two diverging definitions of the term developer experience.

The concept of developer experience has evolved into two different flavors. The first is external-facing, focused on helping external adopters of a company’s API, tool or ecosystem through developer marketing and relations. The second flavor, focused internally, has emerged from companies like Netflix and is aimed at improving the developer’s experience in writing code and getting it into the CI/CD pipeline. This includes onboarding and platform engineering. While this is a positive development, it has caused some confusion about what developer experience is and what directors of developer experience do.

How Go’s Simplicity Brings Complexity

APIMatic.io — Tue, 02 May 2023 19:00:00 +0000

Golang, aka Go, is a modern programming language known for its simplicity, ease of use, and ability to handle high-concurrency tasks. However, this simplicity can sometimes bring complexity to the code you write. As a software developer, I learned this while delving deeper into coding with Go.

Transitioning to a new programming language can be challenging, and Go is no exception. In this article, I’ll explore some of the challenges I faced when migrating to Go from another language.

Navigating the Unintended Complexity in Go

Go-ing Beyond Static Typing: Implementing Polymorphism

The most prominent area (in my experience) where Golang’s simplicity can cause complexity is in polymorphism. Other languages, like .NET, easily implement polymorphism using classes that inherit from a base class. But in Go, things work a little differently.

While Go has polymorphism, it is limited to interfaces only. This means developers have to create interfaces for every structure they build and make sure each class implements those interfaces. This introduces complexity when dealing with polymorphic JSON structures.

I encountered complexity while implementing templates for generating APIMatic’s Golang client SDKs. API definitions with inheritance in their model structures require generated code that supports inheritance and polymorphism. It was a challenging task to work with arrays of polymorphic objects, but I discovered that using custom unmarshaling with a discriminator could help. This discriminator tells the unmarshaller which type of object it is dealing with, so it can convert the interface type into the correct object type and then call that object unmarshaller. unmarshal it.

The Great Error Hunt in Go

Beyond polymorphism, there are other factors making the switch to Go a challenge. For example, Go has a unique style of handling errors. Instead of throwing simple exceptions like other languages, Golang uses multiple return values and error codes. This means an error propagates till it reaches the code that invoked it. This approach leads to more explicit error handling, but it is more verbose and requires implementation of additional error-handling logic.

To illustrate, let’s look at some code with error handling.

// GetLocationById returns Location Coordinates
// if the ID provided is valid else returns an error.

func GetLocationById(id int) (*Coord, error) {
    if id > 0 && id < 10 {
        return &Coord{1, 2}, nil
    }
    return nil, errors.New("unknown id")
}

func main() {
    coord, err := GetLocationById(344)
    if err != nil {
        fmt.Println("An error occurred: ", err)
        return
    }
    fmt.Println("Got the coordinates: ", coord)
}

Smelly Garbage Collection in Go

Among popular server-side programming languages, Go is unique in its use of a garbage collector to manage memory. This is an example of Golang providing simplicity to developers. While garbage collection makes memory management easier for developers, it also exposes risks of performance issues. If not managed properly, garbage collection can introduce additional overhead and latency. This is complexity for developers who write low-latency applications.

Perils of Go’s Dependency Management System

Go does not have a central dependency management system like other languages, and developers typically load dependencies straight from GitHub or any public platform. This makes it simple to work with, but you may spend more time searching for the right package to use.

It isn’t all bad..

While Go’s simplicity can create complexity in some areas, there are still many things to love.

Simplicity in Access Modifiers

I appreciate Golang’s simplicity when it comes to variable access modifiers. Unlike other languages, there are no specific access modifier keywords in Go. Instead, Go has a simple approach to access modifiers: capitalized means public and un-capitalized means private (outside package). This makes it easy to understand and manage the visibility of your code. Here’s an example of how simple access modifiers are in Golang:

// There are only 2 access modifiers in Go; Exported(public) and Unexported(private).

type Sample struct {
    PublicField   bool    // Public/Exported fields in Go have capitalized field names
    privateField  string  // Private/Unexported fields in Go have lowercased first letter of the field name
}

This simple naming convention ensures their code is easy to read and maintain, while still maintaining strong encapsulation.

Go Generics: The Gift that Keeps on Giving

In early 2022, Golang developers released Go generics, which takes a lot of boilerplate code away, making code simpler and easier to work with. This feature allows developers to work with any type of data in a more efficient way.

Go’s Multiple Returns for Cleaner Code

One of the distinctive features of Go is the ability to return multiple values from a function. This allows developers to write clean and concise code that can handle multiple errors or return multiple values without having to resort to using structures or other data types.

This feature is particularly useful in error handling, where a function can return both a result and an error value at the same time, reducing the need for error-checking code throughout the application.

type Coord struct {
    Latitude  int
    Longitude int
}

// GetLocationById returns Location Coordinates
// if the ID provided is valid else returns an error. 

func GetLocationById(id int) (*Coord, error) {
    if id > 0 && id < 10 {
        return &Coord{1, 2}, nil
    }
    return nil, errors.New("unknown id")
}

Code Styling is FTW!

Go has a built-in tool called gofmt, which automatically formats code according to Go conventions. This makes it easy for developers to write clean, consistent code without having to worry about manually formatting it. Additionally, the Go vet tool can help identify subtle issues in code such as unreachable code areas. This helps developers catch errors early on and ensures their code adheres to Go's strict coding standards.

Go-odbye Unused Variables

One of the key benefits of Go is its efficient memory management. Golang's compiler does not allow unused variables in the code, which saves a lot of memory. This means developers cannot accidentally declare dead variables in their code which would consume memory. This helps reduce memory usage and ensure your Go applications run efficiently.

It's Time to Go Now

Working with Go programming language has come with its fair share of challenges. However, I've relished the simplicity and efficiency that this language offers, enabling me to tackle complex tasks with ease. Now, with the power of Go generics, I'm beyond excited to get my hands on this new toolset, which I believe will revolutionize the way I approach coding.

Check out APIMatic blog section for more informative reads.

Launching SDKS.io — A Place for SDK Builders

APIMatic.io — Thu, 20 Apr 2023 16:15:00 +0000

Photo by Corinne Kutz on Unsplash

In this article, we’ll introduce you to sdks.io, why we built it, and our hopes for the future.

What are SDKs

SDKs (software development kits) are collections of software development tools and resources that allow developers to create applications for a specific platform or operating system. SDKs can include libraries, sample code, and documentation, among other resources.

Why SDKs are important

SDKs are important for developers because they abstract away complexity and reduce the amount of code a developer needs to write when integrating with APIs. Companies provide these pre-built components and tools as SDKs making it easier for developers to build robust and feature-rich applications.

Additionally, SDKs can provide developers with support and documentation, which helps them troubleshoot issues and ensure their application is working as intended. This can be especially useful for developers who are new to a platform or who are unfamiliar with its specific tools and resources.

What is SDKs.io

SDKs.io is a site dedicated to improving the state of SDK development. APIMatic has years of experience building SDKs for leading technology companies and our staff includes those who’ve managed SDK programs for API providers. We brought our combined experience together to establish a set of best practices developers can use to build SDKs for consuming RESTful APIs.

At SDKs.io we cover subjects such as design considerations before you start building, guidelines for constructing code libraries, and recommendations for supporting developers through different types of documentation. With this information teams are better equipped to provide software that serves their developer community.

Best Practices

The design section helps teams think big picture and establish guidelines for developing code libraries that are the foundation for an SDK. In preparation, you’ll consider the programming languages and frameworks to support, does your API work for both client and server-side libraries, should you utilize code generation, and should you open source your SDK code. We discuss the importance of idiomatic code and naming conventions and how annotations can be used to power code completion in developer IDEs.

The build section dives deep into the details of building code libraries for APIs. We cover topics such as authentication, translating endpoints into methods, data models, logging, persistent connections, timeouts & retries, and much more. All with an eye towards abstracting away complexity and reducing the amount of code a developer needs to write when integrating with your API.

The support section focuses on ways to support developers through different documentation formats. We look at the pros and cons of open sourcing your code libraries and how to support your SDK users in online forums and through traditional support teams.

Ways to Build

We are advocates of code generation and do a deep dive into OpenAPI generator and APIMatic to show developers how to evaluate these types of solutions. We do our best to examine the tradeoffs between building vs. buying a code generation solution. Of course, homegrown SDKs may be the best way to serve your developer community, and we expect the best practices can help teams who take this approach. We also touch on ways to engage with developers who’ve built their own code libraries and made them available to your community.

SDK Research

Lastly, we’ve kicked off SDK industry research to better understand the SDK programs of leading technology companies. By observing trends and sharing insights we can understand the state of SDK development.

You’ll definitely want to watch this space for interesting insights. For example, we discovered a vast array of programming languages are supported by companies. 18 languages were represented in our SDK survey with JavaScript/TypeScript being the most popular, followed by Python, Java, and Ruby. PHP barely edged out C# for 5th place. A signal of the shifting landscape, Go makes a strong showing in our programming language list along with Swift and Kotlin.

Why did we create SDKs.io

Knowledge about SDK development is out there but tends to be scattered across blog posts written by teams who’ve built SDKs and are not intended to be a guide or a gathering place for the community of SDK builders.

Our aim is to provide a space where builders can share their triumphs and failures on the road to providing a better developer experience. There is no guide to building SDKs and you have to start somewhere, so we started with our experiences and learnings in the space.

This is an ongoing project and will get better over time. We don’t have all the answers and invite others to contribute their stories and experiences building SDKs. We’ve turned on GitHub discussions as a place for conversation with us and each other.

We are human, so if you find an error and can submit an issue or a pull request, we’d really appreciate your help.

What’s next for SDKs.io

We’ve just launched, so feedback from the community would help us understand what you’re finding helpful and how we can improve. Our blog area will serve as a place for guest writers and SDKs news and updates.

SDK research is an area we are very excited about. This research is based on public SDK repositories and developer portals. Ideally, we’d like SDK builders to contribute information about their programs to increase the representation, accuracy, and richness of our data set. Also, what questions would you like answered about SDK trends. We’d love to hear from you and find ways to provide even more valuable insights.

Who is APIMatic

APIMatic builds SDKs and documentation for leading technology companies to enhance their developer experience and drive API adoption. SDKs built with APIMatic have been used by millions of developers.

APIMatic auto-generates SDKs and idiomatic code samples, which developers can copy and paste directly into their codebase. We also generate language-specific documentation, API reference docs, and how-to guides.

The platform includes an API Code Playground that allows developers to make API calls directly from the documentation and modify code in their preferred language to test the results.

Moreover, companies can choose to have documentation hosted by APIMatic, embedded in an existing developer portal, or deployed on their own domain. Updates to the developer experience are automated through full CI/CD integration.

If you’re a developer who wants to learn more about SDKs, you should check out the sdks.io website. With its clear and concise explanations and practical examples, sdks.io aims to help you become a more efficient and effective developer.