Skip to content

OpenAPI Specification

The complete OpenAPI 3.0 specification for STAC Server defines all endpoints, schemas, and extensions.

Viewing the Specification

  • Source File

    View or download the raw OpenAPI YAML file.

    openapi.yaml

  • Swagger Editor

    Interactive viewer with validation and try-it-out features.

    Open in Swagger

  • Redoc Viewer

    Clean, responsive API documentation interface.

    Open in Redoc

  • Generate Clients

    Use OpenAPI generators to create client libraries.

    OpenAPI Generator

Specification Highlights

The STAC Server OpenAPI specification defines:

  • 40+ endpoints covering all STAC API operations
  • Complete schemas for STAC Collections, Items, and search parameters
  • Extension support for Transaction, Query, Filter, Sort, Fields, and Aggregation
  • Error responses following RFC 7807 Problem Details
  • Examples for all request and response types

Using the Specification

Generate API Clients

Use OpenAPI Generator to create client libraries:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate Python client
openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/stac-utils/stac-server/main/src/lambdas/api/openapi.yaml \
  -g python \
  -o ./stac-client-python

# Generate TypeScript client
openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/stac-utils/stac-server/main/src/lambdas/api/openapi.yaml \
  -g typescript-fetch \
  -o ./stac-client-ts

Validate API Responses

Use the specification to validate API responses:

# Install spectral
npm install -g @stoplight/spectral-cli

# Validate API responses
spectral lint openapi.yaml

API Testing

Use the specification with testing tools:

# Dredd API testing
npm install -g dredd
dredd openapi.yaml http://localhost:3000

# Postman collection generation
npx openapi-to-postmanv2 \
  -s openapi.yaml \
  -o stac-server.postman_collection.json

Local Interactive Documentation

When running a STAC Server instance, the /api endpoint provides an interactive Redoc interface:

# Start server locally
npm start

# Visit interactive docs
open http://localhost:3000/api

This interface allows you to:

  • Browse all endpoints with complete schemas
  • View request/response examples
  • Test API calls directly from the browser
  • Download the OpenAPI specification

Specification Conformance

The specification implements:

Next Steps

  • Reference > API Overview - Human-readable API documentation
  • Guides > Usage - Practical examples and tutorials
  • External > STAC API Spec - Official specification