API Guide

OpenAPI Spec

The SpaceTraders API is documented using the OpenAPI Specification. This allows users to generate a client library for the API in many different languages. You can find the repository with our OpenAPI specification here.

Stoplight Studio

We provide access to our API documentation through Stoplight Studio. This allows you to interact with the API directly from your browser and is synced with our OpenAPI specification.

Generating a Client Library

The OpenAPI specification can be used to generate a client library for the SpaceTraders API in many different languages using the OpenAPI Generator .

The following is an example of generating a TypeScript client library using the typescript-axios generator and the bundled specification from Stoplight.

openapi-generator generate \
 -i https://stoplight.io/api/v1/projects/spacetraders/spacetraders/nodes/reference/SpaceTraders.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle \
 -o packages/spacetraders-sdk \
 -g typescript-axios \
 --additional-properties=npmName="spacetraders-sdk" \
 --additional-properties=npmVersion="2.0.0" \
 --additional-properties=supportsES6=true \
 --additional-properties=withSeparateModelsAndApi=true \
 --additional-properties=modelPackage="models" \
 --additional-properties=apiPackage="api"

Bundled References

Our specification file uses the $ref keyword frequently to reference other files. This can cause issues with some OpenAPI generators.

However, Stoplight has a link for the bundled specification that can be used to generate a client library.

Using the Client Library

The generated client library can be used to interact with the SpaceTraders API. The following is an example of using the TypeScript client library to retrieve a list of systems.

import axios from 'axios'
import {
  Configuration,
  Cooldown,
  DefaultApi,
  FleetApi,
  SystemsApi
} from 'spacetraders-sdk'

export const configuration = new Configuration({
  basePath: process.env.BASE_PATH,
  accessToken: process.env.ACCESS_TOKEN
})

export const instance = axios.create({})

// example retry logic for 429 rate-limit errors
instance.interceptors.response.use(undefined, async (error) => {
  const apiError = error.response?.data?.error

  if (error.response?.status === 429) {
    const retryAfter = error.response.headers['retry-after']

    await new Promise((resolve) => {
      setTimeout(resolve, retryAfter * 1000)
    })

    return instance.request(error.config)
  }

  throw error
})

const system = new SystemsApi(configuration, undefined, instance)

system.getSystems().then(console.log)
Previous
Game Concepts