GET/case-studies/stellar-api-docs

Stellar API Documentation

Context

This work was completed during my time at the Stellar Development Foundation in 2022-2023.

Stellar's API documentation kept falling out of sync with their code. I was brought in to read the codebase, work with the engineering team, and create the OpenAPI spec files that now feed directly into their doc generator—so when the spec changes, the website updates automatically.

Context

Stellar is a decentralized payment network for fast, low-cost cross-border transactions.

Horizon is Stellar's REST API for interacting with the network—querying accounts, submitting transactions, and streaming ledger data.

The Anchor Platform handles the bridge between Stellar and traditional finance, managing KYC, deposits, withdrawals, and compliance.

Both APIs serve developers building on Stellar. Both needed documentation that could scale.

The Approach

I was asked to lead the effort of translating Stellar's APIs into a formal OpenAPI specification. There was no existing spec to work from—I had to derive it.

That meant:

Reading the codebase to understand what the APIs actually did, not what the old docs claimed
Reviewing existing documentation to identify gaps and inconsistencies
Interviewing senior engineers to clarify intent, edge cases, and undocumented behavior

From there, I designed a modular file structure where components are defined once and referenced everywhere:

File Structure

openapi/
├── horizon/
│   ├── components/
│   │   ├── endpoints/
│   │   │   ├── accounts.yml
│   │   │   ├── transactions.yml
│   │   │   ├── operations.yml
│   │   │   └── ...
│   │   ├── parameters.yml
│   │   ├── schemas/
│   │   │   ├── accountSchema.yml
│   │   │   ├── transactionSchema.yml
│   │   │   └── ...
│   │   └── examples/
│   │       └── responses/
│   └── main.yml
└── anchor-platform/
    ├── schemas.yaml
    └── bundled-platform.yaml

The key insight: reusability through $ref. Instead of repeating parameter definitions across dozens of endpoints, define them once in parameters.yaml and reference them.

How It Works

Shared Parameters

Common patterns like pagination, sorting, and account IDs are defined once:

39 lines

These four parameters appear across 30+ endpoints. Define once, reference everywhere.

Endpoint Definitions

Endpoints wire together parameters, schemas, and examples through references:

22 lines

Check out the $refs, the endpoint doesn't duplicate definitions, it composes them. The response schema uses allOf to combine the links structure with the account data shape.

The Outcome

The specifications now power the Stellar API documentation, auto-generated through Docusaurus.

What changed:

Single source of truth — The spec is the contract
Update once, propagate everywhere — Change CursorParam and every endpoint using it reflects the change
Docs that can't drift — Generated from the spec means always in sync
Reduced maintenance burden — Adding a new endpoint means composing existing components

Note

The full specification lives in the stellar-docs repo.

Beyond Documentation

The spec files aren't just for docs. Once you have a formal OpenAPI definition, it becomes infrastructure for the entire API lifecycle:

SDK generation — Auto-generate client libraries in Python, JavaScript, Go, etc.
Mock servers — Spin up fake APIs for frontend development before the backend is ready
Contract testing — Validate that the implementation matches the spec
Postman collections — Auto-import endpoints for manual testing
Changelog diffing — Compare spec versions to see exactly what changed between releases