Products & Surfaces

Auto-generated OpenAPI spec

Use the OpenAPI specification that Runtype generates for your API Surface to document endpoints, import them into API tools, and generate client code.

Access the OpenAPI spec

An active API Surface exposes an OpenAPI 3.2.0 specification at the following URL:

https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/openapi.json

Replace the placeholders in the URL:

  • YOUR_PRODUCT_ID: the ID of the Product that contains the API Surface.
  • YOUR_SURFACE_ID: the ID of the API Surface.

Request the YAML document at the corresponding path with .yaml in place of .json. Find both links in the Endpoints tab of your API Surface.

What’s included

The generated spec describes the active API Surface with the following content:

  • Endpoints: paths and methods for capability endpoints.
  • Schemas: request and response body definitions.
  • Authentication: bearer token and X-API-Key header security schemes.
  • Error responses: standard error formats and status codes.
  • Metadata: the API version, Product name and description, and contact details.

Import the spec into API clients

Use the import workflow for your API development tool.

Import the spec into Postman

To import the spec into Postman, follow these steps:

  1. Open Postman.
  2. Click Import.
  3. Select Link.
  4. Enter the OpenAPI spec URL.
  5. Click Import.

Postman creates a collection from the spec.

Import the spec into Insomnia

To import the spec into Insomnia, follow these steps:

  1. Open Insomnia.
  2. Click Create > Import from URL.
  3. Enter the OpenAPI spec URL.
  4. Click Fetch and Import.

Insomnia imports the endpoints from the spec.

Import the spec into Bruno

To import the spec into Bruno, follow these steps:

  1. Open Bruno.
  2. Right-click the collection.
  3. Select Import > OpenAPI.
  4. Enter the OpenAPI spec URL.

Bruno imports the OpenAPI document into the collection.

Generate client code

Use the OpenAPI Generator to generate a TypeScript client from the JSON spec:

$npx @openapitools/openapi-generator-cli generate \
>  -i https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/openapi.json \
>  -g typescript-fetch \
>  -o ./src/api-client

Replace YOUR_PRODUCT_ID and YOUR_SURFACE_ID with the IDs for your Product and API Surface. OpenAPI Generator supports TypeScript, Python, Go, Java, Ruby, PHP, and other languages.

Validate the spec

Use the Swagger Parser package to validate the JSON spec before you use it with an API client:

1import SwaggerParser from '@apidevtools/swagger-parser'
2
3const api = await SwaggerParser.validate(
4  'https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/openapi.json'
5)
6console.log('API name: %s, version: %s', api.info.title, api.info.version)

Replace YOUR_PRODUCT_ID and YOUR_SURFACE_ID with the IDs for your Product and API Surface.

Keep the spec in sync

The spec reflects changes to the API Surface after you:

  • Add or remove Capabilities.
  • Change Capability configurations.
  • Update Product settings.

Refresh your imported spec and regenerate client code after these changes.

Authentication

Request the JSON or YAML spec without authentication. Send a valid API key with requests to the Capability endpoints that the spec describes.

Update the Product metadata

The spec derives info.title from the Product’s name and info.description from the Product’s description. If the Product has no description, the spec uses a default description. To change these values, edit the Product’s name or description in Product settings.

Next steps

Choose a next step: