APIs That Developers Love

We rewrote our API three times. Not because the technology was wrong, but because developers hated using it. The first version was RESTful. The second was GraphQL. The third was something else entirely.

The lesson: good API design isn't about following patterns. It's about removing friction.

The Principle of Least Surprise

Developers bring mental models from other APIs. Violate them at your peril.

We made this mistake with pagination. Our first API used cursor-based pagination everywhere. Developers expected offset/limit. They built wrappers. They complained. Support tickets piled up.

The fix wasn't technical. We added offset/limit as an alternative, even though it's less efficient. Developer happiness increased. Support tickets disappeared.

Sometimes the right technical choice is the wrong product choice.

Consistency Over Correctness

Every endpoint should feel like it came from the same API. Same error formats. Same naming conventions. Same authentication.

We enforce this with automated linting:

Rules:
- All timestamps are ISO 8601 with timezone
- All IDs are URL-safe base64
- All errors use RFC 7807 Problem Details
- All list endpoints support filtering by created_at

Violations fail the build. Not because they're wrong, but because inconsistency is confusing.

The First Request Matters

A developer's first API call happens within five minutes of finding your docs. If it fails, they leave.

We optimize for this moment:

No setup required. Our sandbox API works without authentication. Rate limited, but functional. Developers can explore before committing.

Copy-paste examples. Every endpoint has a complete curl command. Not partial snippets. Complete commands that work when pasted into a terminal.

Immediate feedback. The response includes a request ID. The docs explain how to use it to debug. Developers feel supported, not abandoned.

Error Messages Are Documentation

Bad error: 400 Bad Request

Good error:

{
  "type": "https://api.example.com/errors/invalid-date-format",
  "title": "Invalid date format",
  "status": 400,
  "detail": "Expected ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ), got '2026-13-45'",
  "instance": "/api/v1/events",
  "invalid_params": [{
    "name": "start_date",
    "reason": "month must be between 1 and 12"
  }]
}

The error teaches the developer how to fix it. No need to open the docs. No need to contact support.

Versioning Without Pain

APIs change. The question is how to communicate that change.

We use a hybrid approach:

URL: /api/v2/users
Headers: 
  Accept: application/vnd.api+json; version=2026-02-15
  Sunset: 2026-06-01 (for deprecated features)

Breaking changes bump the URL version. Additive changes use header versioning. Deprecated features include a Sunset header with the removal date.

Developers can pin to a specific version and upgrade when ready. No surprise breakages.

SDKs Are Not Optional

REST is great for tools. SDKs are great for humans. We generate official SDKs for TypeScript, Python, Go, and Rust.

The SDKs aren't thin wrappers around HTTP. They're idiomatic libraries:

// TypeScript
const client = new SunsetClient({ apiKey });
const user = await client.users.create({
  email: '[email protected]',
  name: 'Developer'
});

// Rust
let client = SunsetClient::new(api_key)?;
let user = client.users().create()
    .email("[email protected]")
    .name("Developer")
    .send().await?;

Type safety. Auto-completion. Idiomatic error handling. The API becomes invisible. Developers think in their language, not HTTP.

Observability Is a Feature

Developers need to debug their integrations. We provide:

- Request logs in the dashboard
- Webhook delivery status with retry history
- OpenAPI specs that validate in real-time
- Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset)

Transparency builds trust. When something breaks, developers can see why. They're not flying blind.

The Measure of Success

We track one metric: time to first successful request. Not signups. Not API calls. Time from finding our docs to making a working request.

When this number drops, we know we're doing something right. When it rises, we investigate. The goal is under five minutes. Always.

Great APIs don't just work. They welcome developers in and make them want to stay.