The Code Samples API

NOTE

This feature is for Speakeasy Enterprise customers. To inquire about access, please contact a Speakeasy representative, or book a demo.

Overview

The Speakeasy Code Samples API is a streamlined solution for accessing rich, up-to-date SDK usage examples for Speakeasy managed SDK’s. These examples can be easily integrated into an organization’s documentation sites, tools, or developer portal, and they’ll stay up to date automatically.

This API is ideal for organizations who:

• Use Speakeasy to generate SDKs from OpenAPI specifications,
• Need reliable, up-to-date SDK usage examples for their APIs, and
• Want custom tooling for SDK code samples in their documentation.

Usage

Prerequisites

IMPORTANT

To use the Code Samples API, the following prerequisites are required:

• A Speakeasy Enterprise Subscription,
• An Automated Code Sample URL, configured for the desired Speakeasy SDK, and
• A Speakeasy API Key for the workspace associated with the desired SDK.

TypeScript SDK

The Code Samples SDK can be used in TypeScript projects to fetch snippets. The library also ships with some convenient features such as React Query hooks, and a React Component.

For instructions on how to install and use the TypeScript SDK, refer to the GitHub repo’s README file (opens in a new tab).

The React Component

This library includes a React component that fetches and highlights code snippets using codehike. Along with displaying the snippet, it shows a loading state during fetching and provides a fallback view if an error occurs.

The component can be used as follows:

import { SpeakeasyCodeSamplesCore } from "@speakeasyapi/code-samples/core";
import {
  CodeSampleFilenameTitle,
  CodeSamplesViewer,
  SpeakeasyCodeSamplesProvider,
} from "@speakeasyapi/code-samples/react";

const speakeasyCodeSamples = new SpeakeasyCodeSamplesCore({
  apiKey: "<YOUR_API_KEY_HERE>",
  registryUrl: "https://spec.speakeasy.com/org/ws/my-source",
});

function App() {
  return (
    <SpeakeasyCodeSamplesProvider client={speakeasyCodeSamples}>
      <CodeSamplesViewer
        copyable
        defaultLang={"typescript"}
        title={CodeSampleFilenameTitle}
        operation={"getPassageText"}
        // client={speakeasyCodeSamples} 
        // 👆 optional, if you want to pass the client directly 
        // instead of using the context provider
      />
    </SpeakeasyCodeSamplesProvider>
  );
}

REST API Reference

Retrieve usage snippets

GET /v1/code_sample

Retrieves usage snippets from an OpenAPI document stored in the registry. The endpoint supports filtering by programming language and operation ID.

Query Parameters

registry_url required, type: string

• Description: The registry URL from which to retrieve the snippets
• Example: https://spec.speakeasy.com/my-org/my-workspace/my-source

operation_ids type: string[]

• Description: The operation IDs to retrieve snippets for
• Example: getPets

method_paths type: { method: string, path: string }[]

• Description: The method paths to retrieve snippets for
• Example: [{"method": "get", "path": "/pets"}]

languages type: string[]

• Description: The programming languages to retrieve snippets for
• Example: ["python", "javascript"]

Example Request

curl -G "https://app.speakeasy.com/v1/code_sample" \
  -H "X-Api-Key: <SPEAKEASY_API_KEY_HERE>" \
  --data-urlencode "registry_url=https://spec.speakeasy.com/my-org/my-workspace/my-source" \
  -d "languages=go" \
  -d "languages=typescript" \
  -d "operation_ids=getPets"

Example Response

{
  "snippets": [
    {
      "operationId": "getPetById",
      "path": "/pet/{id}",
      "method": "get",
      "language": "typescript",
      "code": "import { Petstore } from \"petstore-sdk\";\n\nconst petstore = new Petstore({\n  apiKey: \"<YOUR_API_KEY_HERE>\",\n});\n\nasync function run() {\n  const result = await petstore.pet.getById({\n    id: 137396,\n  });\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
    }
  ]
}

{
  "status_code": 404,
  "message": "no snippets found for given operation IDs and languages -- err_not_found: not found"
}