DEV Community: Nolan Di Mare Sullivan

Everything You Need to Know About OpenAPI

Nolan Di Mare Sullivan — Tue, 23 Apr 2024 09:39:22 +0000

Speakeasy has released a comprehensive, Open Source reference to writing OpenAPI specifications.

The reference has AI-search built in to help you quickly answer any questions that you may have.

If you are interested in contributing, the github repo can be found here.

Why is OpenAPI Important?

Because API design is important. An API that developers enjoy interacting with turns a SaaS business into a platform. However great design is only useful if it's well-documented and consistently represented across every API surface area (docs, SDKs, etc.).

That is where OpenAPI comes in. Trying to manually create & maintain all your surfaces will inevitably lead to frustration and inconsistencies. Instead, if you are building a RESTful API, OpenAPI will be (should be) the source of truth that automates the creation of all your public surfaces (docs, SDKs, etc.).

This documentation will help you understand the OpenAPI Specification.

What is OpenAPI?

When we refer to OpenAPI, we mean the OpenAPI Specification - a standardized document structure for describing HTTP APIs in a way that humans and computers can understand.

OpenAPI files are written as JSON or YAML, describing your API using a standard vocabulary defined by the Specification - we'll call this JSON or YAML file an OpenAPI document.

A valid OpenAPI document describes your RESTful API and serves as the instruction set for tooling that generates API documentation, SDKs, and more. We will refer to an app or tool that reads an OpenAPI document to perform an action as an OpenAPI tool. Speakeasy is one such tool, a full list can be found here.

OpenAPI Document Basics

Your OpenAPI document is composed of keywords (some required, some optional). Together, the document covers the key elements of your API:

What security is required to access it?
Which endpoints expose which resources?
How are those resources constructed?

openapi: 3.1.0
info:
  title: The Speakeasy Bar
  version: 1.0.0
servers:
  - url: https://speakeasy.bar
    description: The production server
security:
  - apiKey: []
tags:
  - name: drinks
    description: Operations related to drinks
paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
components:
  schemas:
    Drink:
      type: object
      title: Drink
      properties:
        name:
          type: string
        price:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header

To break that down piece by piece:

openapi: The version of the OpenAPI Specification that the document conforms to, should be one of the supported versions.

openapi: 3.1.0

Note: Speakeasy tooling currently only supports OpenAPI Specification versions 3.0.x and 3.1.x.

info: Contains information about the document including fields like title, version, and description that help to identify the purpose and owner of the document.

info:
  title: The Speakeasy Bar
  version: 1.0.0

servers: Contains an optional list of servers the API is available on. If not provided, the default URL is assumed to be /, a path relative to where the OpenAPI document is hosted.

servers:
  - url: https://speakeasy.bar
    description: The production server

security: Contains an optional list of security requirements that apply to all operations in the API. If not provided, the default security requirements are assumed to be [], an empty array.

security:
  - apiKey: []

tags: Contains an optional list of tags that are generally used to group or categorize a set of Operations.

tags:
  - name: drinks
    description: Operations related to drinks
paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks

paths: Contains the paths and operations available within the API.

paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 
                    "#/components/schemas/Drink"

components: Contains an optional list of reusable schemas that can be referenced from other parts of the document. This improves the readability and maintainability of the document by allowing common schemas to be defined once and reused in multiple places.

components:
  schemas:
    Drink:
      type: object
      title: Drink
      properties:
        name:
          type: string
        price:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header

Format and File Structure

An OpenAPI document is a JSON or YAML file that contains either an entire API definition or a partial definition of an API and/or its components. All field names in the specification are case-sensitive unless otherwise specified.

A document can be split into multiple files, and the files can be in different formats. For example, you can have a JSON file that contains the API definition and a YAML file that contains the components, or a collection of files that contain partial definitions of the API and its components.

Generally, the main API definition file is called openapi.json or openapi.yaml, and the component files are called components.json or components.yaml, though this is not a requirement.

Some common organizational patterns for OpenAPI documents are:

A single file that contains the entire API definition.
A main file that contains the API definition and a components file that contains the components.
- This is normally achieved by using the $ref keyword to reference the components file from the main file. Click here for more information on references.
A collection of files that contain partial definitions of the API and its components.
- Some tools support this pattern by allowing multiple files to be provided. Others, such as the Speakeasy Generator, require the individual files to be merged into a single file before being passed to the tool, which can be achieved using the Speakeasy CLI tool. Click here for more information on the Speakeasy CLI merge tool.

How is this different to the official OpenAPI documentation?

The goal of this documentation is to provide a practioner's guide for developers interested in understanding the impact of OpenAPI design on their downstream API surfaces. This guide prioritizes approachability and practicality over technical completeness.

We've structured the documentation according to the needs of OpenAPI users of any skill level.

Which versions of the OpenAPI Specification does this documentation cover?

There are several versions of the OpenAPI specification in circulation: 2.0 (also known as Swagger), 3.0, and 3.1. We recommend developers use OpenAPI version 3.1 for all projects. The advantage of using OpenAPI version 3.1 is that it is fully compatible with JSON Schema, which gives you access to a much larger ecosystem of tools and libraries.

Speakeasy's documentation covers versions 3.0.x and 3.1.x of the OpenAPI specification. Where there is an important difference between the two versions, we call it out specifically, otherwise the documentation will apply to both versions.

SDK Best Practices

Nolan Di Mare Sullivan — Sun, 16 Jul 2023 19:54:54 +0000

From API-First to SDK-First

Do the best APIs have SDKs?

One of the most significant trends in tech over the past ten years has been the proliferation and success of API-as-a-product companies (e.g. Twilio, Algolia, etc).

But the term API-as-a-product obscures one of the most critical ingredients in these companies’ success. The secret that the most successful API companies have been hiding in plain sight, is that their APIs are not the actual interface beloved by users. It is their SDKs that are at the heart of the best-in-class developer experience these companies offer. If you want to delight developers, don’t try to just be API-first, focus on becoming SDK-first.

So why doesn’t every API company offer SDKs to their users? Up until now, it’s been really hard to sustainably build great SDKs. If you look at a list of the most popular APIs, you’ll find that even some of the biggest API companies have failed to build out robust SDK programs. Many offer patchy or incomplete support.

Change is coming though. Speakeasy is committed to giving every company access to an API experience platform on par with what the best API companies provide. A major component of that platform is a workflow to easily and sustainably build SDKs for all your REST APIs.

In this piece, we’ll discuss why SDKs are important, what qualities make a great SDK, and how to overcome the common problems that typically plague SDK development and maintenance.

Why Are SDKs Important?

SDKs provide numerous unique benefits to your end-users’ developer experience, and to your team too:

Reduce your team’s support burden: By enabling type definitions in the IDE, SDKs reduce the likelihood of user error during user integration. That in turn means fewer support tickets for your team to manage.
Improve product discoverability: SDKs put your product in the place where developers are most likely to look for solutions. Client libraries on Github and in popular package managers will help your product develop social proof as users encounter you in familiar environments.
Increase revenue with a larger addressable market: Every SDK you offer makes it easier to appeal to a new community of developers. That means an increase in users, and ultimately, more revenue.

Of course, releasing a badly-written SDK could do more harm than good. Let’s dive into what it means to build a great SDK.

Best Practices for a Great SDK

We’ve talked to hundreds of developers on this topic. While there is always a bit of personal preference, these are the things that every developer wants to see in an SDK:

1. Type Safe

Type safety might be the most important aspect of SDK creation. By making your API’s inputs and outputs explicit, the developers integrating the API into their application can better understand how the API is intended to be used — and massively reduce the number of incorrect requests being made to your API. Type safety will help developers debug in their IDE as they write the application code, and spare them the frustration of having to comb through the constructed data object to see where/ mistakes occurred.

The more that you can include in your type definition, the more feedback developers will have when they are building with your SDK. Below you can see the benefit of working with a strongly-typed SDK:

// Pet class generated by Speakeasy
export class Pet extends SpeakeasyBase {
    @SpeakeasyMetadata({ data: "form, name=category;json=true" })
    @Expose({ name: "category" })
    @Type(() => Category)
    category?: Category;

    @SpeakeasyMetadata({ data: "form, name=id" })
    @Expose({ name: "id" })
    id?: number;

    @SpeakeasyMetadata({ data: "form, name=name" })
    @Expose({ name: "name" })
    name: string;

    @SpeakeasyMetadata({ data: "form, name=photoUrls" })
    @Expose({ name: "photoUrls" })
    photoUrls: string[];

    /**
     * pet status in the store
     */
    @SpeakeasyMetadata({ data: "form, name=status" })
    @Expose({ name: "status" })
    status?: PetStatus;

    @SpeakeasyMetadata({ data: "form, name=tags;json=true", elemType: Tag })
    @Expose({ name: "tags" })
    @Type(() => Tag)
    tags?: Tag[];
}

NOTE

Note the @SpeakeasyMetadata decorators that the Speakeasy SDK uses to serialize and deserialize data, depending on the use case. The example above includes instructions on how to serialize a Pet object and its related objects, Tag and Category. The @Expose and @Type decorators expose types at runtime.

2. Abstracted

SDKs spare your users from having to worry about the minutiae of how your API works. You can abstract away details like:

Networking code: SDKs can handle the details of making network requests to an API. This allows developers to focus on the functionality they want to implement, rather than the details of how to communicate with the API.
Request and response formatting: SDKs can handle the details of formatting requests and parsing responses in a format that is specific to the API
Error handling: SDKs can interpret the details of errors that occur when using an API, allowing developers to focus on their application logic rather than error handling.

3. Human Readable

This one is pretty self-explanatory. AI hasn’t made developers obsolete yet, so there is going to be another person on the other side of your SDK code. When code is well-organized, well-commented, and easy to read, developers are more likely to be able to understand how the SDK works and how to use it correctly.

4. Limited Dependencies

Codebases are jungles, and SDKs are another component of this complex ecosystem. When an SDK has a large number of dependencies, it can be more difficult to use the SDK with other libraries and frameworks. If a developer has to try and resolve incompatible dependencies before they can use your SDK, there is a high risk they will abandon the API integration altogether.

Limiting the number of external dependencies in your SDK is therefore critical to ensure compatibility.

5. Enterprise Features

We think that features like retries, pagination, and security helpers should come in every SDK. These aren’t things that are strictly required at the earliest stages of integration, but as soon as users want to use your API for production use cases, this matters — and their absence can slow down integrations significantly. It’s just another case where a user doesn’t want to have to think about how to do this well — and may not have enough product context do to so optimally.

The API creator is in a much better position to set sensible defaults here.

x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500        # 500 milliseconds
    maxInterval: 60000          # 60 seconds
    maxElapsedTime: 3600000     # 5 minutes
    exponent: 1.5
  statusCodes:
    - 5XX

Language Idiomatic

This is a meaty topic, and it’s hard to discuss in generalities (it’s different for every language), so let’s walk through an example of the type of design choices that a developer might expect of a Go SDK:

Minimal dependencies and relying on the Go standard library as much as possible.
Struct tags and reflection-based (de)serializers to define how the types we generate are correctly serialized based on the OpenAPI document.
Pointers for optional objects including fields/parameters/response and request bodies to ensure that the user can differentiate between a field not being set and a field being set to a zero value.
A Utils package that improves readability by bundling the methods for configuring the SDK and serializing/deserializing the types we generate into a shared package, avoiding the need to duplicate in each method.

package shared

type PetStatusEnum string

const (
    PetStatusEnumAvailable PetStatusEnum = "available"
    PetStatusEnumPending   PetStatusEnum = "pending"
    PetStatusEnumSold      PetStatusEnum = "sold"
)

type Pet struct {
    Category  *Category      `json:"category,omitempty"`
    ID        *int64         `json:"id,omitempty"`
    Name      string         `json:"name"`
    PhotoUrls []string       `json:"photoUrls"`
    Status    *PetStatusEnum `json:"status,omitempty"`
    Tags      []Tag          `json:"tags,omitempty"`
}

If you make sure your SDK is type safe, idiomatic, and compatible with their existing environment you’re going to attract developers and inspire loyalty. At this point the last thing that needs to be solved is building a sustainable program for your SDK development.

How to Sustainably Build SDKs

When you start building SDKs you will quickly run into two major issues:

There are a lot of languages that you’ll need to build support for
You need a way to update SDKs as your API changes.

Let’s walkthrough how you can overcome these two blockers.

The Long-tail of languages and runtimes

In 2022, the proliferation of programming languages accelerated — and there’s no sign of that trend abating anytime soon.

That’s great for nerding out over language design, but it’s a pain if you’re on the hook for building your API’s SDKs. Whereas 15 years ago you could have covered most programmers with 3-4 libraries, it’s now probably closer to 8-10. Languages can also have multiple popular frameworks, each of which require idiosyncratic tweaks to get the developer experience correct.

This fragmentation of languages & runtimes makes it harder to provide the same level of service to your users and makes it hard to keep track of how users are interfacing with your product.

It’s not reasonable to expect that every company will have the language expertise internally to be able to support every language & runtime. That’s why we’ve built the Speakeasy generator. We are committed to building out support for every popular language & runtime so that you don’t have to. And in cases where people need something very specific, we offer the ability to right a custom template for the generator to use.

Preventing SDK Drift

Too many companies think of building SDKs as a one-time project. They assign developers or contractors to handroll SDKs in the languages they know best, and punt on a long-term support system. This works for a while, but inevitably an expanding API definition, and an increasing number of libraries saddles the engineering team with a constant stream of tedious refactoring work. This refactoring may or may not be prioritized leading to SDKs with divergent behavior.

The best API companies have built SDK generators and workflows that update the SDK automatically as part of their CI/CD pipeline. Whenever a new version of the API is published, a new version of their SDKs is released.

This is a huge lift for any company to undertake — which is where Speakeasy comes in. With Speakeasy, any development team can have the same API infrastructure as the world’s best API companies. Producing idiomatic SDKs as part of your CI/CD is now available with our generator and a simple Github action:

Final Thoughts

What’s considered table stakes for developer experience has never been higher. And as the primary interface for APIs, your SDKs are perhaps the single most important component of your developer experience. At the same time, the proliferation in languages & runtimes being used in production applications means it’s never been harder to support the developer community.

When you are building SDKs, make sure you build something that developers will actually want to use. That means making sure your SDKs are type-safe and idiomatic. Finally, make sure that your SDK development is sustainable. Make sure you have a plan to provide ongoing support to the SDKs you build, otherwise, you risk developers losing trust in the product when SDKs are not at parity with the API.

If you want to make your SDK creation and ongoing support easy to manage, consider trying out the Speakeasy pipeline.

APIs vs SDKs: Why you should always have both

Nolan Di Mare Sullivan — Mon, 22 May 2023 22:18:16 +0000

What are APIs and SDKs? We explore the different use cases that each addresses, what great APIs or SDKs look like, and explain why you need both.

What’s an API?

An API, or Application Programming Interface, allows different software applications to communicate with each other. For example, a developer in an e-commerce company might create an “orders” API that enables other services to easily retrieve orders made by a certain user. Consumers of the API may be external developers or even other developers within the same company.

There are several different API technologies. Let’s look into the most popular in 2023: REST, GraphQL and gRPC

REST (Representational State Transfer): REST is the most widely used approach for creating APIs, primarily due to its simplicity and compatibility with HTTP. It dictates structured access to resources via well-known CRUD (Create/Read/Update/Delete) patterns. A common pattern in modern web development is to create a front-end written in React or a similar framework, which fetches data from and communicates with a back-end server via a REST API.
GraphQL: GraphQL is a newer API technology that enables API consumers to request only the data they need. This reduces bandwidth required and improves performance, and is particularly suitable in situations where a REST API returns large amounts of unnecessary data. However, GraphQL is more complex to implement and maintain, and users need to have a deeper understanding of the underlying data models and relationships in order to construct the right queries.
gRPC (Google Remote Procedure Call): gRPC is a high-performance, open-source framework designed for low-latency and highly-scalable communication between microservices. gRPC is strongly-typed, which helps catch errors earlier in the development process and improves reliability. However, gRPC ideally requires support for HTTP/2 and protocol buffers, which many web and mobile clients may not support natively. Also note that far fewer developers are familiar with gRPC than REST, which can limit adoption. For these reasons, gRPC is mainly used for internal microservice communications.

In summary, REST remains the most popular API technology due to its simplicity and widespread adoption. GraphQL and gRPC are popular for specific use cases.

Why are APIs important?

There are several use cases for APIs:

Leverage the Best: Third party APIs provide developers easy access to services that would take years to build. With just a few lines of code, developers can add payment capabilities (e.g. Stripe), mapping data (e.g. Google Places API), or transactional email (e.g. Resend) into their application, all powered by 3rd parties. This allows developers to stay focused on the value add of their app, and outsource the rest.
Scale Applications: By providing a well-defined programmatic interface, APIs allow developers to build their applications more efficiently, as they can update or replace individual components without affecting the entire system.
Collaborate Efficiently: APIs can be used internally to facilitate collaboration between teams by standardizing communication and providing a clear contract for developers to work against. Common functionalities are developed into services and APIs so that they can be leveraged by every team – accelerating the development of new applications and reducing duplicative work.

What is an SDK?

An SDK, or Software Development Kit, contains libraries, documentation, and other tools that aim to make it easy to integrate with an API in a specific language. It simplifies integrating with an API – without the developer needing to dig through docs to patch together details like how the API handles auth, query parameters, or returns response objects.

The idea is that providing an intuitive and streamlined way to integrate with an API enables developers to quickly and easily access the API's functionality. Which is, after all, the goal of an API developer right?

If this sounds a little academic, hang on for the code examples shortly.

A typical SDK contains:

API client: A pre-built client that handles communication with the API, taking care of low-level details like HTTP requests, authentication, and error handling.
Data models: Classes or structures that represent the API's data objects, providing a strongly-typed and native representation of the data returned by an API.
Helper functions and utilities: These assist developers in performing common tasks related to the API, such as data serialization, pagination, or error handling.
Documentation and code samples: These should be written specifically in the SDK’s language.

Why use an SDK? Why are they important?

It’s worth diving a bit deeper on why SDKs for an API are so important.

Without an SDK, developers have to manually handle the API integration process. This is time-consuming and error-prone. For example, developers need to:

Read the API documentation, and especially the expected request and response data formats.
Write code to form and send HTTP requests to the relevant API endpoints, parse the responses into the right data structures, and handle any errors that might occur.
Manage the low-level details of authentication, retries, and rate limiting. The latter often are left out in the initial stages of integrating with an API, but are incredibly important if the API is being used in critical workflows.

Overall, this approach tends to resemble “trial and error”, which creates a high risk of users introducing bugs into the integration. API users end up frustrated and less motivated to use the API.

However, with a language-idiomatic SDK, developers can avoid these common pitfalls. This results in a faster integration process, and greater API usage as API consumers are provided with a reliable, well-supported – even enjoyable! – experience.

SDKs offer several advantages over the APIs alone:

Faster development: SDKs provide pre-built functions that help developers accomplish tasks quickly. For example, an SDK for an e-commerce API might include a pre-built function and parameters for placing an order.
Standardized / streamlined data and type definitions: SDKs can ensure that data returned by an API is handled in a standard and recommended manner.
Consistency: By offering standardized components and best practices, SDKs promote consistency, making maintenance and management much easier. This might be particularly important for internal APIs, where you don’t want every API user to create an idiosyncratic implementation.
Breaking change mitigation: When an API introduces breaking changes, the SDK can in some cases be updated to accommodate those changes “under-the-hood” – while maintaining a consistent interface for the developers.
Streamlined documentation: SDK docs focus on achieving specific outcomes and abstract away many low-level details, making them more usable, easier to understand, and ultimately more effective for developers.

Example of integrating to an API with and without an SDK

To highlight these differences, let’s look at an example of what integrating with an e-commerce API might look like, first without an SDK and then with one.

The use case will be enabling a new customer to place an order. This requires fetching information about the product being ordered, creating a new customer, and creating the order itself.

First, here’s what integrating might look like without an SDK:

const fetch = require('node-fetch');

const apiKey = 'your_api_key';
const baseUrl = 'https://api.ecommerce.com/v1';
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

const productName = 'Awesome Widget';
const customer = {
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com'
};
const quantity = 2;

async function placeOrder(productName, customer, quantity) {
  try {
    // Step 1: Get product information
    const productResponse = await fetch(`${baseUrl}/products`, { headers });

    if (productResponse.status !== 200) {
      throw new Error(`Could not fetch products. Status code: ${productResponse.status}`);
    }

    const productData = await productResponse.json();
    const product = productData.products.find(p => p.name === productName);

    if (!product) {
      throw new Error(`Product '${productName}' not found.`);
    }

    // Step 2: Create a new customer
    const customerResponse = await fetch(`${baseUrl}/customers`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ customer })
    });

    if (customerResponse.status !== 201) {
      throw new Error(`Could not create customer. Status code: ${customerResponse.status}`);
    }

    const customerData = await customerResponse.json();
    const customerId = customerData.customer.id;

    // Step 3: Place the order
    const orderResponse = await fetch(`${baseUrl}/orders`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        order: {
          customerId,
          items: [
            {
              productId: product.id,
              quantity
            }
          ]
        }
      })
    });

    if (orderResponse.status !== 201) {
      throw new Error(`Could not place order. Status code: ${orderResponse.status}`);
    }

    console.log('Order placed successfully!');
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

placeOrder(productName, customer, quantity);

Note that the API consumer would need to construct all this code themself. They would need to refer to the API documentation to figure out which APIs should be called, what the response data structures look like, which data needs to be extracted, how to handle auth, what error cases might arise and how to handle them… oof!

Now here’s the SDK version of this code:

const { EcommerceClient } = require('ecommerce-sdk');

const apiKey = 'your_api_key';
const client = new EcommerceClient(apiKey);

const productName = 'Awesome Widget';
const customer = {
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com'
};
const quantity = 2;

async function placeOrder(productName, customer, quantity) {
  try {
    await client.placeOrder(productName, customer, quantity);
    console.log('Order placed successfully!');
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

placeOrder(productName, customer, quantity);

Notice how much simpler and concise it is. Authentication is handled automatically with the developer just needing to copy in their key. Pre-built functions mean the developer doesn’t need to parse through pages of API docs to stitch together the required calls and associated data extraction themselves. Error handling and retries are built-in.

Overall, a far easier and superior experience.

What’s the difference between SDKs and APIs?

In summary, APIs & SDKs are symbiotic. Let’s talk about coffee to draw the analogy better.

You can think of APIs as the fundamental, bare metal interfaces that enable applications or services to communicate. In our analogous example, APIs are like going to a coffee shop and getting a bag of beans, a grinder, a scale, filter paper, a coffemaker/brewer, kettle, and an instruction guide. Good luck making a delicious brew!

SDKs on the other hand are critical to enabling APIs to reach their full potential, by providing a rapid, ergonomic way to access the API’s underlying functionality. In our coffee example, SDKs are more akin to telling a skilled barista “I’d like a latte please”. The barista does all of the work of assembling the ingredients, and you get to focus on the end result.

API and SDK best practices

Now we know what APIs and SDKs do, what should you keep in mind as you’re building them, to ensure they fulfill the promises we’ve outlined above?

Here are some “gotchas!” to watch out for when building awesome APIs:

Design carefully: It can be extremely difficult to get users to change how they use an API once it’s in production. Avoiding unnecessary breaking changes, where possible, will save you many headaches and irate users later.
Documentation: In addition to an “API reference” that details every endpoint and response, consider creating a “usage guide” that walks users through how to use APIs in sequence to accomplish certain tasks.
Authentication: Creating and sending users API keys manually works fine for an MVP, but has obvious security and scalability challenges. An ideal solution is to offer a self-service experience where end-users can generate and revoke keys themselves. For more on API auth, check out our guide.
Troubleshooting and support: Users will inevitably run into issues. It’s easy for members of the team to quickly get inundated with support requests. Try to provide self-service tools for troubleshooting API issues, such as logging and monitoring, and community support channels.

Building great SDKs presents a different set of considerations. Keep these in mind if you want to offer a great SDK to your users:

How stable is the underlying API? If the API is undergoing frequent changes, it might be particularly challenging to manually keep the SDKs up-to-date and in sync with the API.
Creation and maintenance cost: Creating native language SDKs for all your customers’ preferred languages can be a huge hiring and skills challenge. Each language SDK also has to be updated every time the API changes – ideally in lockstep to avoid the SDK and API being out of sync. This is time-consuming and costly. Many companies have deprecated or scaled back their SDKs after misjudging the work required.
Testing and validation: Plan for thorough testing of the SDKs across different platforms and languages, including unit tests, integration tests, and end-to-end tests, to ensure the SDKs are reliable and compatible with the API.
Documentation: Provide clear examples and code snippets in each language to make the SDKs easy to use and understand.

APIs, SDKs and Speakeasy

As discussed above, APIs and SDKs are both incredibly important tools.

Unfortunately however, creating SDKs for every API has been out of reach for most teams, given their cost, the skills required, and distraction from the core product roadmap.

Until now.

At Speakeasy, we believe that every API deserves an amazing SDK – one that is idiomatic, reliable, low-cost, always-in-sync, and easy to manage.

And that’s exactly what you get with Speakeasy:

Idiomatic: we know how important it is that the SDK feels ergonomic. That’s why we built a generator from the ground up with a focus on creating idiomatic SDKs in a range of languages.
Reliable: our SDKs have been battle-tested in real-world scenarios through our customers. And we handle all support and troubleshooting – so you don’t have to.
Low-cost: until now, only the largest companies have been able to afford an engineering team to focus on SDKs. Speakeasy provides access to best-in-class SDKs for a fraction of the price of a full engineering team.
Always-in-sync: our SDKs rebuild after every API spec change.
Easy to manage: we offer a fully-featured web application so you can always understand the current status of your SDK generation.

Read our case study with Vessel, a unified API for CRM and sales, to learn more about us.

If you have an API spec, why not try it for yourself now? Just click the button below to generate your first SDKs for free.

Idiomatic SDKs for OpenAPI

Nolan Di Mare Sullivan — Tue, 06 Dec 2022 15:31:24 +0000

Our SDK Generator

Client SDKs are a bit like vodka, they’re either handcrafted and very expensive, or they’re cheap and leave you with nothing but regrets and a hangover. To get an SDK with a good developer experience, companies have historically needed to invest significant resources in handrolling their own. The only other option is using bare-bones OSS offerings.

We’re providing a middle path; a free-to-use SDK generator that provides the foundation for a great developer experience with no investment required. We've launched with support for Go, Python, Typescript, and Java (alpha). We plan to add Ruby as well as other languages soon!

What constitutes a great developer experience is of course subjective, but we focused on:

Fully typed so that SDKs feel like they have been written by a human: easy to read and debug.
Batteries included where everything from retries to pagination of your APIs is handled as part of the SDK generation (Available in our closed beta).
Easy to use, our SDK generators are fault tolerant, and designed to always output usable SDKs where possible. If we can't output a usable SDK, we will provide human readable error messaging about why validation of your OpenAPI spec failed (instead of just failing silently or with obscure error messages or giving you a broken SDK)
Full OpenAPI Coverage, We plan to have broad coverage of the OpenAPI specs while having a deep focus on the most common ways of defining an API and ensuring you have a nice to use SDK as the output.

To illustrate the differences between our SDK generator and the open source examples, we’ve run the canonical Petshop Example through both and compared the output. But the TLDR is:

The Speakeasy SDK generator is installed with brew with no additional dependencies
No NPM. No Java. Everything is packaged in a self-contained binary
We support less languages for now but the ones we do are more idiomatic, so that usage feels natural per language.
We provide a simple API to the SDKs that is easy to mock and test.
The SDKs we produce have fully typed outputs including enums and more.

The generator has been battle tested on thousands of APIs and we are sharing the results in our github repo. If you want to try it out on your own, download the CLI or brew install and get started in minutes:

brew install speakeasy-api/homebrew-tap/speakeasy
speakeasy generate sdk -s openapi.yaml -o ./sdk -l go

Our Experience using OpenAPI generator

Before we get into the details of how our SDK generator compares with others, we wanted to walk through the experience with the OpenAPI generator that led to this product being created in the first place. It will probably be quite familiar to those who have used the OpenAPI tooling.

Installation

Ours was a struggle from the word go. If you look at the openapi-generator website, it will direct you to ‘Try NPM’ to install the CLI. The key word here is ‘Try’, because there is no guarantee of success. We had multiple issues not already being setup for using NPM:

Had permissions issues installing globally via NPM
Got an error “Error: /bin/sh: 1: java: not found” when first run.

To resolve the issue, we had to install both NPM and Java before we could get the installation working. We had better luck with the homebrew install instruction further down the page. They worked on the first attempt at installation, downloading all the required dependencies.

Schema Validation

Validating our OpenAPI spec worked fine and was a great start to using the openapi-generator.

openapi-generator validate -i openapi.yaml           
Validating spec (openapi.yaml)
No validation issues detected.

SDK Generation

Even though our schema had been deemed valid by the tool, we ran into issues when we began trying to generate a Go SDK from our openapi yaml. The error that we received was most unhelpful and we weren’t able to determine why our spec might have been causing issues.

openapi-generator generate -i openapi.yaml -g go -o ../speakeasy-client-sdk-go-openapi-gen
...
Exception: Property and is missing from getVars
        at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1187)
        at org.openapitools.codegen.DefaultGenerator.processPaths(DefaultGenerator.java:1078)
        at org.openapitools.codegen.DefaultGenerator.generateApis(DefaultGenerator.java:580)
        at org.openapitools.codegen.DefaultGenerator.generate(DefaultGenerator.java:915)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:465)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
Caused by: java.lang.RuntimeException: Property and is missing from getVars
        at org.openapitools.codegen.DefaultCodegen.addRequiredVarsMap(DefaultCodegen.java:7319)
        at org.openapitools.codegen.DefaultCodegen.addVarsRequiredVarsAdditionalProps(DefaultCodegen.java:7354)
        at org.openapitools.codegen.DefaultCodegen.fromParameter(DefaultCodegen.java:4972)
        at org.openapitools.codegen.DefaultCodegen.fromOperation(DefaultCodegen.java:4394)
        at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1155)
        ... 6 more

Direct Comparison with Petshop Example

Let’s move onto an example that does work with the openapi-generator, the canonical Petstore API from the OpenAPI specification. First let’s take a look at the commands used to generate SDKs:

OpenAPI:

openapi-generator generate -i petstore.yaml -g go -o ./openapi

Speakeasy:

speakeasy generate sdk -s petstore.yaml -o ./speakeasy -l go

The OpenAPI and Speakeasy generators both output usable SDKs for the Petstore API. We’re using Go for this example, but our generator supports Go, Python and Typescript. Note that the openapi generator supports a large array of additional languages that we plan to add to the speakeasy generator down the road.

While the OpenAPI generator does support many languages, as we were looking through we felt that the SDKs for languages like Go were actually quite Java-like and less idiomatic to the Go language:

OpenAPI:

ctx := context.Background()
  client := openapi.NewAPIClient(openapi.NewConfiguration())
  ctx = context.WithValue(ctx, openapi.ContextAccessToken, "special-key")
  r := client.PetApi.FindPetsByStatus(ctx)
  r = r.Status("pending")
  pets, res, err := r.Execute()
  if err != nil {
    log.Fatal(err)
  }
  if res.StatusCode != 200 {
    log.Fatalf("unexpected status code: %d", res.StatusCode)
  }
  data, _ := json.Marshal(pets)
  fmt.Println(string(data))

Speakeasy:

ctx := context.Background()
  sdk := speakeasy.New()
  status := operations.FindPetsByStatusStatusEnumPending
  queryParams := operations.FindPetsByStatusQueryParams{Status: &status}
  security := operations.FindPetsByStatusSecurity{
    PetstoreAuth: shared.SchemePetstoreAuth{
      Authorization: "Bearer special-key",
    },
  }
  res, err := sdk.FindPetsByStatus(ctx, operations.FindPetsByStatusRequest{
    QueryParams: queryParams,
    Security:    security,
  })
  if err != nil {
    log.Fatal(err)
  }
  if res.StatusCode != 200 {
    log.Fatalf("unexpected status code: %d", res.StatusCode)
  }
  data, _ := json.Marshal(res.Pets)
  fmt.Println(string(data))

The openapi-generator’s SDK is also harder to mock due to the multiple method calls required to set up a request and execute it. With the Speakeasy SDK, a single method call is sufficient.

It’s also worth looking at the formatting and styling for each of the SDKs generated where there are some differences:

The openapi-generator outputs comments to help with usage (coming soon for the speakeasy generator).
The openapi-generator generated a lot of additional getter/setter, instantiation and serialization methods that aren’t required and just reduce the readability of the SDKs code.
The OpenAPI SDK code lacks formatting, whereas our SDK code is formatted idiomatically.
Our generator generated full types for everything (where possible).

That last point we feel is quite important. For example, OpenAPI treats enums as strings, whereas we generate typed enums reducing usage errors. Our support for enums comes at the cost of supporting a single edge case of the Petstore API, which allows status enums to be provided as comma separated strings to filter on multiple status, this could be overcome by defining in the OpenAPI spec that the type is an array of enums instead of just a string.

OpenAPI:

// Pet struct for Pet
  type Pet struct {
    Id *int64 `json:"id,omitempty"`
    Name string `json:"name"`
    Category *Category `json:"category,omitempty"`
    PhotoUrls []string `json:"photoUrls"`
    Tags []Tag `json:"tags,omitempty"`
    // pet status in the store
    Status *string `json:"status,omitempty"`
  }

  // NewPet instantiates a new Pet object
  // This constructor will assign default values to properties that have it defined,
  // and makes sure properties required by API are set, but the set of arguments
  // will change when the set of required properties is changed
  func NewPet(name string, photoUrls []string) *Pet {
    this := Pet{}
    this.Name = name
    this.PhotoUrls = photoUrls
    return &this
  }

  // NewPetWithDefaults instantiates a new Pet object
  // This constructor will only assign default values to properties that have it defined,
  // but it doesn't guarantee that properties required by API are set
  func NewPetWithDefaults() *Pet {
    this := Pet{}
    return &this
  }

  // GetId returns the Id field value if set, zero value otherwise.
  func (o *Pet) GetId() int64 {
    if o == nil || o.Id == nil {
      var ret int64
      return ret
    }
    return *o.Id
  }

  // GetIdOk returns a tuple with the Id field value if set, nil otherwise
  // and a boolean to check if the value has been set.
  func (o *Pet) GetIdOk() (*int64, bool) {
    if o == nil || o.Id == nil {
      return nil, false
    }
    return o.Id, true
  }

  // ... And continues with getters/setters for every field

Speakeasy:

type PetStatusEnum string

  const (
    PetStatusEnumAvailable PetStatusEnum = "available"
    PetStatusEnumPending   PetStatusEnum = "pending"
    PetStatusEnumSold      PetStatusEnum = "sold"
  )

  type Pet struct {
    Category  *Category      `json:"category,omitempty"`
    ID        *int64         `json:"id,omitempty"`
    Name      string         `json:"name"`
    PhotoUrls []string       `json:"photoUrls"`
    Status    *PetStatusEnum `json:"status,omitempty"`
    Tags      []Tag          `json:"tags"`
  }

Summary

Hope people found that comparison to be interesting/useful. We look forward to hearing feedback on how we can improve our SDK generators and what we should build next. If you have any questions, please join our slack community and you can message us directly.

Definitive Guide to API DevEx Portals

Nolan Di Mare Sullivan — Tue, 29 Nov 2022 13:57:14 +0000

Why You Need A Portal If You Want to Serve Developers

When you’re teaching a kid to drive, you don’t hand them a car key, the operation manual for the car and then leave them to figure it out. Of course you could, but not everyone would get the car moving, and there might be some easily avoided accidents along the way.

But this is exactly how many companies teach people to use their APIs: they hand over a stack of documentation, an API key and call it a day. Of course, those tools are important; without them, your users are stuck at ‘Go’. But these tools alone don’t really deliver any sort of experience to users. It’s basic. It’s lackluster. It’s an experience, but probably not THE developer experience you want to give your users. It’s certainly not a delightful experience or memorable enough to tell others about. And that lackluster experience has a material impact on the adoption and usage of your API.

If developer experience has been underinvested in, a common set of issues begin to pop up:

The average time gap between user signup and first successful request is longer than one day.
Your team spends hours every week troubleshooting client integrations.
The average number of API calls & endpoints made by users isn’t expanding over time.

Resulting in:

Decreased API adoption and usage
A higher cost to support for each user.
A reduced LTV for each user.

To address these issues you need to vastly improve your API’s DevEx. The key to a great user experience is providing your users with an API DevEx Portal which makes your API:

Accessible: there is zero friction to begin sending API requests.
Understandable: users are able to get immediate feedback on their API usage – and to self-service troubleshoot issues when they do occur.
Usable: It is trivially easy for users to discover and test out new use cases for your API that naturally expand their usage.

But what tooling gets you to this point? Let’s walk through each of the above criteria and discuss the specific tools that can help you give your API users the DevEx they deserve.

What Tooling Does Your API Portal Need

Accessible

Making the API accessible means making it as easy as possible for users to make that first API call. 99% of companies are still stuck somewhere in this first stage.

Key Capabilities:

API Documentation - There has been a pervasive view that documentation equals great DevEx. We think that documentation is only the first step: it’s critical, but on its own it will still leave your API users wanting. Documentation should be comprehensive, easy to navigate / search, and have code snippets / examples embedded. Ideally, docs should enable users to try the API without any additional tooling or configuration. API docs should also differentiate between API reference (a full list of all endpoints, parameters, response codes, etc.) and usage guides (tutorials that take users step-by-step through how they can use the API to accomplish key tasks).
Auth Login - If you want to offer developers a more personalized experience, auth is the prerequisite. You need to know who someone is before you can issue them an API key, and start giving them tools to help them understand and track their usage. Login should of course be managed by a single shared identity service e.g. auth0 or other system of record – you don’t want to build a separate user management system for your application and your API for example.
API Key Management - Nobody wants to have to fill in a typeform and wait for customer support to review before they can get started with an API. If there’s no way for a developer to create keys on their own, most will never convert into users of your product. By the time someone has reviewed their access request, they will have moved on to a new priority, or found an alternative solution. If the API interfaces with sensitive data, and a review process is a legal requirement for production credentials, then enable users to provision sandbox keys without review (more on Sandboxes below).

Understandable

Even companies where APIs are the primary surface area often struggle to make the investment required to advance their developer portal to being understandable.

Key Capabilities:

API Request Viewer - When debugging, there’s no substitute for being able to step through things one at a time. A request viewer makes it possible for your users to view the full list of requests they’ve sent to your API – without creating additional work for your team to pull logs, send screenshots via email or Slack, or jump on a Zoom call. Without a self-service request viewer, broken integrations create poor API experience and leads to churned clients. A request viewer should provide users the ability to filter by time, response code, endpoint and more, and ideally allow users to edit and replay the request for quick debugging.

-‍ API Usage Metrics - A request viewer is only useful to developers if they know there’s an issue to investigate. That is why it’s important to surface key usage metrics in real time – so that users know the overall health of their integration. Usage metrics should place an emphasis on error reporting and significant changes in usage so that your users can take corrective action to any errors or unintended changes.

API Status Page - Developers need a place to check if APIs are experiencing downtime. Nothing is more frustrating than having to email a company, “is your API working?” An API status page brings transparency, and transparency is important for building trust with your users.

Usable

Usability tooling is focused on making it easy to test out new API use cases and also making those new use cases easy to find. Usability tooling shines as APIs become larger. Early on an API will serve a single use case, and documentation will focus on supporting that use case. As the API’s surface area grows, documentation becomes denser, and isolating relevant instructions becomes challenging. Usability tooling will help insulate users against this by providing structure for the documentation, and making it easier to test out new use cases.

Key Capabilities:

Client SDKs - You need to meet your developers where they already are. Providing client SDKs makes it easier for developers to get started with your API by grounding them in the familiarity of their favorite language, and significantly reducing the amount of boilerplate they need to write. This is especially true if your SDKs can handle auth, pagination, and retries and others. They are therefore great at helping maximize your audience while minimizing support costs. But it’s not enough to have SDKs, it’s critical that the SDKs are developer-friendly, meaning that they are language idiomatic and human readable. Unfortunately, creating client SDKs is prohibitively expensive for most API teams, since they need to be created and updated by hand. While open source generators exist, the SDKs they output are often buggy and not ergonomic.
API Runbooks - We think of runbooks as live usage guides. They take users step-by-step through the process of using your API to accomplish specific tasks, but also show relevant, live API requests in real-time. This helps to focus developers on the key use cases required to complete API integrations. Your customers can use them to grow their usage of your API. As an API builder, runbooks also help you understand the maturity of your customer base: you can begin to understand your API usage as a customer funnel, and start to measure where and why users drop out of the funnel.
API Sandbox - Probably nothing helps more with adoption than giving developers an easy way to play with your API. A sandbox can give prospective users a way to use your APIs without needing to sign up for an account. Developers are more likely to trust an API if they’ve seen it working before needing to hand over their information. And a sandbox can give existing users a way to learn by doing, and without any risk of corrupting production workflows. This enables users to easily expand their use cases for your API.

How to get to Best-In-Class: Build or Buy?

The list above is presented as a rough roadmap. To improve your DevEx, just build each of the tools listed above in order, and you can progress from having no tooling, to having a great Developer Portal.

But as any PM or engineer will tell you, knowing what to build is only the beginning. Finding the resources required to build is the real battle. Great DevEx is extremely important for a successful API, but building all of the above is a huge commitment of resources, requires significant ongoing maintenance, and likely isn’t a core competency for your organization. As a result, investing in Developer Experience continues to be the project that is slated for next quarter.

For almost every company therefore, investing in a best-of-breed solution makes more sense. With an API DevEx Portal from a company like Speakeasy, your customers get a world-class API Developer Experience in days instead of quarters, your product roadmap has negligible impact, and your eng teams don’t need to reinvent the wheel.

Furthermore, our product is designed with maximum flexibility in mind, giving you the best of both worlds. Every tool in our API DevEx Portal is a React component, and can be customized, branded and extended as you need. Similarly, our platform can be self-hosted or run in our Speakeasy Cloud depending on your requirements.

Final Thoughts

For a long time, companies have been able to get by with substandard developer experiences, but that is beginning to change. Developer Experience is now getting the attention it deserves, and we are rapidly reaching an inflection point. What has been previously considered great DevEx is becoming table stakes for developer products.

We know that DevEx isn’t ignored because companies don’t see the value. Rather, it’s the result of painful prioritization decisions. That’s why Speakeasy exists. We don’t want anyone to have to ever make that tradeoff. With Speakeasy you can get a best-in-class, composable developer portal up and running in a matter of minutes. If you want to learn more, join our beta program or come chat with us in our Slack!

An Improved OpenAPI SDK Generator

Nolan Di Mare Sullivan — Wed, 31 Aug 2022 16:37:58 +0000

What We’ve Built

We’re excited to publicly launch an SDK generator that improves upon the OpenAPI service. In our view the biggest problem with the OpenAPI generator was that it produced client libraries that were untyped and unopinionated. That’s why we focused on building a generator that is able to handle typing correctly and is opinionated about what makes for a good SDK:

Low-dependency - To try and keep the SDK isomorphic (i.e. available both for Browsers and Node.JS servers), we wrap axios, but that’s it.This is intended to be idiomatic typescript; very similar to code a human would write; with the caveat that the typing is only as strict as the OpenAPI specification.
Static Typing - At this point static typing is everywhere. So wherever possible, we generate typed structures, construct path variables automatically, pass through query parameters, and expose strictly typed input / output body types.
Language idiomatic & opinionated - There’s value in being neutral, but we felt like there is more value in being opinionated. We’ve made choices for how things like Pagination, Retries (Backoff/Jitter etc), Auth integrations, should be handled in the SDK.

Why We Think SDKs Are Important

A good developer experience means flattening the learning curve by meeting developers where they already; that’s why every company with an API platform should strive to offer SDKs for integrating with their APIs. Language-idiomatic SDKs improve user productivity by removing the need for writing the boilerplate required to send API requests and parse response objects. Companies that offer SDKs get faster adoption, spend less time troubleshooting, and provide an overall better developer experience.

We look forward to hearing from the community what they think of the service. We’d love to know what else people would want to see included in a generator. What other languages would people want to see supported?

The REST Template Project

Nolan Di Mare Sullivan — Wed, 03 Aug 2022 15:50:45 +0000

Github Repository: speakeasy-api/rest-template-go

Building a RESTful API can be daunting for developers who have never done it before (and even those who have). There are a number of choices and best practices that need to be considered as part of an API’s implementation; it can be hard to know where to start. That’s why we’re pleased to announce the RESTful API template project. Over the coming months, we will release RESTful API templates for the most used programming languages – starting today with Go.

This is the template that our team forks from when we are building new APIs. The repo contains a CRUD API for a ‘user’ resource which incorporates the best practices needed for a basic REST service. Our hope is that developers can use this as a foundation upon which to build their own sets of APIs.

The service represents our team’s opinionated stance about what makes for good RESTful API code. Specifically, the template gives you a service which is:

Entity-based: The resources available should represent the domain model. Each resource should have the CRUD methods implemented (even if not all are available to API consumers). In our template, we have a single resource defined (users.go). However other resources could be easily added by copying the template and changing the logic of the service layer.
Properly Abstracted: The transport, service, and data layers are all cleanly abstracted from one another. This makes it easy to apply updates to your API endpoints.
Consistent: It's important that consumers of a service have guaranteed consistency across the entire range of API endpoints and methods. In this service, responses are consistently formatted whether successfully returning a JSON object or responding with an error code. All the service's methods use shared response (http.go) and error (errors.go) handler functions to ensure consistency.
Tested: We believe that a blend of unit and integration testing is important for ensuring that the service maintains its contract with consumers. The service repo therefore contains a collection of unit and integration tests for the various layers of the service.
Explorable: It is important for developers to be able to play with an endpoint in order to understand it. We have provided Postman collections for testing out the REST endpoints exposed by the service. There is a Bootstrap Users collection that can be run using the Run collection tool in Postman that will create 100 users to test the search endpoint with.

We look forward to hearing from the community what they think of the repo. We’d love to know what else people would want to see included in a template: versioning, pagination, authentication? Would people want to see more advanced features?

Choosing Between SASS vs CSS Modules vs CSS-In-JS

Nolan Di Mare Sullivan — Mon, 18 Jul 2022 16:32:50 +0000

We are in the midst of building the first version of our API Ops platform. One of the components which we are actively building is a developer console where devs can get an overview of their APIs and each endpoint’s performance. While building our UI, we are debating many of the fundamental front end architecture decisions that will shape our UI development. One of the biggest debates thus far was whether we would use SASS or CSS-In-JS for our styling.

We know developers are facing these same questions every day, so we want to publish our thoughts in case they are useful to anyone else. Ultimately, we chose to move forward with CSS-In-JS as our primary styling mechanism for reasons specific to our business:we considered it important for the UIs we build to be easily embeddable within external UIs. We felt that CSS-In-JS was the best option for embeds, because integrators wouldn’t need to worry about dealing with style injection, and could theme our components into their style.

We’d love to know your thoughts and how you reached decisions about styling your UI? Have you had any bad experiences with CSS-In-JS?

Below is our full internal conversation only minimally edited for brevity:

If you’re interested in learning more about what we’re up to, please reach out!

DEV Community: Nolan Di Mare Sullivan

Everything You Need to Know About OpenAPI

Why is OpenAPI Important?

What is OpenAPI?

OpenAPI Document Basics

Format and File Structure

How is this different to the official OpenAPI documentation?

SDK Best Practices

From API-First to SDK-First

Do the best APIs have SDKs?

Why Are SDKs Important?

Best Practices for a Great SDK

1. Type Safe

2. Abstracted

3. Human Readable

4. Limited Dependencies

5. Enterprise Features

Language Idiomatic

How to Sustainably Build SDKs

The Long-tail of languages and runtimes

Preventing SDK Drift

Final Thoughts

APIs vs SDKs: Why you should always have both

What’s an API?​

Why are APIs important?​

What is an SDK?​

Why use an SDK? Why are they important?​

Example of integrating to an API with and without an SDK​

What’s the difference between SDKs and APIs?​

API and SDK best practices​

APIs, SDKs and Speakeasy​

Idiomatic SDKs for OpenAPI

Our SDK Generator

Our Experience using OpenAPI generator

Installation

Schema Validation

SDK Generation

Direct Comparison with Petshop Example

Summary

Definitive Guide to API DevEx Portals

Why You Need A Portal If You Want to Serve Developers

What Tooling Does Your API Portal Need

Accessible

Understandable

Usable

How to get to Best-In-Class: Build or Buy?

Final Thoughts

An Improved OpenAPI SDK Generator

What We’ve Built

Why We Think SDKs Are Important

The REST Template Project

Github Repository: speakeasy-api/rest-template-go

Choosing Between SASS vs CSS Modules vs CSS-In-JS

What’s an API?

Why are APIs important?

What is an SDK?

Why use an SDK? Why are they important?

Example of integrating to an API with and without an SDK

What’s the difference between SDKs and APIs?

API and SDK best practices

APIs, SDKs and Speakeasy