Greenpeppersoftware

API documentation is the interface to your interface. It’s the first thing a developer touches after deciding your API might solve a problem, and it’s often the last thing they read before walking away from the integration. For teams of 20–200 engineers, documentation isn’t a nice-to-have artifact. It’s a support-cost multiplier, an adoption lever, and a quiet statement about how seriously you take the people building on your work. This article covers REST APIs, webhooks, SDK generation, and the internal documentation systems that keep them honest. It’s not about GraphQL, except where the contrast clarifies a REST decision.

Good API documentation cuts down on “how do I…” tickets, shortens time-to-first-call, and makes your API feel predictable. Bad documentation does the opposite: it creates a shadow support team, breeds workarounds, and turns your changelog into a horror story. The goal here is practical, no-nonsense guidance for mid-to-senior engineers who own or influence documentation at companies where the API is a product, not a side effect.

Start with the Developer’s First Question: “What Can I Do with This?”

Most API docs fail before the first endpoint. They open with authentication, base URLs, and a wall of parameters. That’s like handing someone a map of the kitchen before telling them what’s for dinner. The first 150 words of your documentation should answer three questions: what is this API for, what can I build with it, and what do I need to know before I start. If a developer can’t answer those questions in under a minute, you’ve already lost them.

For a REST API, that means a short, concrete overview with a real use case. Not “Our API provides programmatic access to your data.” Something like: “Create a webhook that fires when an invoice is paid, then use the Invoices endpoint to fetch the line items and post them to your accounting system.” That sentence tells a developer what the API does, what they can build, and which endpoints matter. It also sets the stage for the semantic cluster that follows: resources, representations, HTTP methods, status codes, pagination, rate limits, and error handling.

Adjacent concepts matter here. Developers will look for terms like idempotency, webhook signatures, sandbox environments, API keys, OAuth scopes, and versioning. If your documentation doesn’t use those words in the places developers expect them, they’ll assume the feature doesn’t exist. That’s not a documentation problem; it’s a trust problem.

Structure Documentation Like a Decision Tree, Not a Novel

Developers read documentation in short, goal-directed bursts. They’re not reading for pleasure. They’re trying to answer a question and get back to their code. Your structure should reflect that. Use a hierarchy that moves from concept to task to reference, and make each level scannable.

The Three-Layer Model

Most effective API documentation follows a three-layer model:

• Concepts – what the API does, how it thinks about resources, and the mental model behind it.
• Guides – step-by-step instructions for common tasks, like “Create your first webhook” or “Handle pagination.”
• Reference – the endpoint-by-endpoint details: methods, parameters, request bodies, response schemas, and error codes.

This isn’t a new idea. It’s the same structure used by Stripe, Twilio, and most developer tools that people actually enjoy using. The difference is that those teams treat the three layers as a single system, not three separate documents. A developer should be able to jump from a concept to a guide to a reference without losing context.

For a REST API, the reference layer is where most of the pain lives. Every endpoint should include:

• The HTTP method and path, with a clear description of what it does.
• Authentication requirements, including scopes or roles.
• Request parameters, with types, defaults, and constraints.
• A request example that actually works.
• A response example with the full schema, not a truncated version.
• Error codes and what they mean in plain language.

If you’re generating SDKs from an OpenAPI specification, the reference layer is also your source of truth. That means the spec must be complete and accurate, not just “good enough for the docs site.” A missing nullable field or an undocumented error code will show up as a bug in every generated SDK. That’s a maintainability problem, not a documentation problem.

Write for the Developer Who Is Slightly Annoyed

Your reader isn’t a blank slate. They’ve probably integrated with other APIs, and they have opinions about how those integrations went. They’re slightly annoyed because they have to learn yet another API, and they’re hoping yours won’t waste their time. Write for that person.

That means:

• Use the imperative mood. “Call POST /invoices to create an invoice.” Not “The POST /invoices endpoint can be used to create an invoice.” The first sentence tells the developer what to do. The second tells them what’s possible. They want the first.
• Put the example first. Show the request and response before explaining every parameter. Developers learn by pattern matching, not by reading prose.
• Be specific about errors. “Returns a 400 error if the amount is negative” is more useful than “Returns an error for invalid input.” The first sentence tells the developer what to fix. The second tells them to guess.
• Avoid jargon that only your team uses. If you call something a “ledger entry” internally, but every other API calls it a “transaction,” use “transaction.” Consistency with the wider ecosystem reduces cognitive load.

Dry humor has a place here, but only if it doesn’t mock the reader. A note like “If you send a DELETE request to /invoices, you will delete all invoices. This is not a bug. It is a feature with excellent documentation.” That kind of aside can make a dense reference page feel less like a tax form. But use it sparingly. The goal is to deflate hype, not to turn your docs into a stand-up routine.

Webhooks: Document the Contract, Not Just the Payload

Webhooks are the part of API documentation that most teams get wrong. They document the payload, but they forget the contract. A webhook isn’t just a POST request to a customer’s server. It’s a promise about delivery, retries, ordering, and security. If you don’t document that promise, developers will build fragile integrations and then blame you when they break.

For every webhook event, document:

• The event name and trigger. What exactly causes this event to fire? Is it fired once per resource, or can it fire multiple times?
• The payload schema. Include every field, even the ones that seem obvious. A missing id field will cause more support tickets than any other single omission.
• Delivery semantics. Do you retry failed deliveries? How many times? What’s the backoff schedule? Do you guarantee at-least-once or at-most-once delivery?
• Security. How do you sign requests? What header contains the signature? How should the receiver verify it? If you don’t document this, developers will either ignore it or invent their own scheme.
• Ordering. Are events delivered in the order they occurred? If not, say so. A developer who assumes ordering and then sees events arrive out of order will spend hours debugging a problem that isn’t theirs.

Here’s a before-and-after example for a webhook section:

Before:

POST /webhooks/invoice.paid
Body: { "invoice_id": "inv_123" }

After:

POST /webhooks/invoice.paid
Trigger: Fires when an invoice transitions to paid status.
Delivery: At-least-once. Retries up to 5 times with exponential backoff.
Ordering: Not guaranteed. Use the event timestamp to order events.
Security: Signed with HMAC-SHA256. Signature in X-Signature header.
Body: {
  "invoice_id": "inv_123",
  "amount_paid": 1000,
  "currency": "usd",
  "paid_at": "2025-01-15T14:30:00Z"
}

The second version answers the questions a developer will actually ask. The first version creates those questions.

SDK Generation: Documentation as a Build Artifact

If you generate SDKs from an OpenAPI specification, your documentation isn’t just a website. It’s a build input. That changes how you write it. Every description, every example, every schema constraint becomes part of the generated code. A vague description like “The amount” becomes a useless comment in the SDK. A missing enum becomes a stringly-typed parameter that invites bugs.

Treat your OpenAPI spec as code. Review it in pull requests. Lint it for missing descriptions, inconsistent naming, and invalid examples. Run a contract test that verifies the spec matches the actual API behavior. If the spec and the API disagree, the SDK will be wrong, and the documentation will be a lie. That’s worse than no documentation at all.

For teams that maintain SDKs in multiple languages, the spec is the single source of truth. That means the spec must be complete enough to generate idiomatic code in each language. A field that’s optional in the API but required in the SDK is a bug. A response schema that omits a nullable field will cause a runtime error in a strongly typed language. These aren’t documentation issues; they’re API design issues that documentation exposes.

One practical approach: write the spec first, then generate the documentation and the SDKs from it. If the spec is good, both outputs are good. If the spec is bad, you’ll see the problems in both places, which is exactly what you want. The alternative—writing docs and SDKs by hand and trying to keep them in sync—is a recipe for drift and resentment.

Internal Documentation Systems: The API Docs You Don’t Publish

Not all API documentation is public. Internal APIs—the ones your own frontend, mobile apps, and services use—need documentation too. In fact, they need it more, because the consumers are your colleagues, and they won’t hesitate to interrupt you with questions.

An internal documentation system for APIs should answer the same questions as a public one, but with a different audience. Your colleagues already know the domain. They don’t need a conceptual overview of what an invoice is. They need to know which endpoint to call, what permissions they need, and what changed in the last deploy.

Practical tips for internal API docs:

• Keep them close to the code. A docs/ folder in the same repository is easier to maintain than a separate wiki. If the docs aren’t in the pull request, they won’t be updated.
• Document the contract, not the implementation. Your colleagues don’t need to know which database table backs an endpoint. They need to know the request and response shapes, the error codes, and the rate limits.
• Use a changelog. Every breaking change should be documented in a way that’s easy to scan. A developer who upgrades a dependency and sees a new error should be able to find the explanation in under a minute.
• Make the docs searchable. If your internal docs are a pile of Markdown files with no search, they’re not docs. They’re a scavenger hunt.

Internal documentation is also where you can be more candid. You can write “This endpoint is slow because it does a full table scan. Don’t call it in a loop.” That kind of note would be embarrassing in public docs, but it’s exactly what your colleagues need to avoid a production incident.

Checklist: Before You Publish

Here’s a checklist you can use before publishing or updating API documentation. It’s not exhaustive, but it covers the failures that cause the most developer pain.

• Can a new developer make their first successful API call in under 10 minutes? If not, the getting-started guide is too long or too vague.
• Does every endpoint have a working request example? Copy-paste the example and run it. If it fails, fix it.
• Are all error codes documented with plain-language explanations? “500 Internal Server Error” isn’t an explanation. “500: The request timed out because the upstream payment provider didn’t respond” is.
• Are webhook delivery semantics documented? Retries, ordering, and security aren’t optional details.
• Is the OpenAPI spec linted and tested? If you generate SDKs, the spec is code. Treat it that way.
• Does the changelog clearly mark breaking changes? A developer should never discover a breaking change by reading a stack trace.
• Are the docs searchable and scannable? Headings, tables, and code blocks should do the heavy lifting. Prose should be short.

Decision Matrix: REST vs. GraphQL for Documentation Effort

This article is about REST, but a brief contrast with GraphQL can clarify a documentation decision. If you’re choosing between REST and GraphQL for a new API, the documentation burden is a real factor.

For a team of 20–200 engineers, REST often wins on documentation effort because the tooling is more mature and the mental model is simpler. GraphQL can be the right choice for complex, client-driven data needs, but the documentation burden is higher. That’s not a reason to avoid GraphQL; it’s a reason to budget for it.

FAQ

How long should API documentation be?

Long enough to answer every question a developer will ask, and no longer. A good rule of thumb: the getting-started guide should be under 500 words. The reference for each endpoint should be under 300 words, not counting examples. If you need more than that, the API is probably too complex, or the documentation is repeating itself.

Should I document every possible error code?

Yes, but group them. Document the errors that are specific to each endpoint, and have a shared section for common errors like authentication failures, rate limits, and validation errors. A developer should never see an undocumented error code. If your API can return it, your docs should explain it.

How do I keep documentation in sync with the API?

Generate it from a spec, and test the spec against the API. If you’re using OpenAPI, run a contract test in CI that verifies the spec matches the actual responses. If you’re not using a spec, start. Hand-written docs that aren’t generated from a spec will drift. It’s not a question of if; it’s a question of when.

What is the most common mistake in API documentation?

Omitting the “why.” Developers don’t just need to know what an endpoint does; they need to know when to use it and what happens if they use it wrong. A parameter description like “The amount” isn’t documentation. “The amount to charge, in the smallest currency unit (e.g., cents for USD). Must be positive. If negative, the API returns a 400 error.” That is documentation.

For more on how documentation fits into a broader engineering culture, see our upcoming piece on internal documentation systems and how they reduce support load. If you have a documentation horror story or a pattern that works, send it in. We read everything, and we’re not afraid to name names—politely.

Build versus buy is the decision that quietly shapes your codebase, your team’s calendar, and your API’s long-term maintainability. It sits at the intersection of engineering capacity, total cost of ownership, and developer experience. For teams maintaining REST APIs, webhooks, and SDKs, the wrong call usually shows up six months later as a brittle internal service nobody wants to own. This article gives you a repeatable framework for making the call without a week of meetings.

Most build-versus-buy discussions fail because they start with features instead of constraints. A vendor demo can make any product look like a fit. A greenfield prototype can make any internal build look cheap. The framework below forces the conversation toward the things that actually predict regret: integration surface, maintenance burden, and the cost of switching later.

Start with the integration surface, not the feature list

When a team says “we could build that in a sprint,” they are usually describing the happy path. The real cost lives in the edges: retry logic, idempotency keys, webhook signature verification, rate-limit handling, and the error taxonomy your API consumers will depend on. A purchased tool may cover 80% of the feature list, but if it forces a different event schema or a proprietary retry model, you have just bought a second integration project.

Before comparing options, write down the contracts the solution must honor. For a REST API team, that means:

• Request and response schemas your clients already consume
• Authentication and authorization boundaries
• Idempotency and retry semantics
• Webhook delivery guarantees and signature verification
• Rate-limit and quota behavior

If a vendor product cannot honor those contracts without a shim layer, the “buy” price is not the subscription. It is the shim, the support burden, and the future migration when the vendor changes their API.

The three-question filter

Use this filter before any detailed comparison. If the answer to any question is “no,” the decision is probably already made.

1. Is this capability a differentiator for our product?

If your customers choose you because of your webhook reliability or your SDK ergonomics, do not outsource the core. A vendor will optimize for the average customer, not for your specific delivery guarantees. The exception is when the capability is table stakes and your team adds no unique value by owning it.

2. Can we maintain it for at least three years without heroics?

Internal builds are not free after launch. They need monitoring, dependency updates, security patches, and an on-call rotation. If the team that builds it will be reorganized in two quarters, the build is a liability. Be honest about team stability before committing.

3. What is the cost of switching in 18 months?

Every choice is reversible in theory. In practice, a purchased tool that stores state in a proprietary format or an internal service that becomes load-bearing in your API path can both be expensive to replace. Estimate the migration cost now, not when the pain appears.

A decision matrix that fits on one page

Use this matrix during the first working session. Score each option from 1 (poor) to 5 (excellent). Do not average the scores; look for disqualifying lows.

One common failure mode: teams score “build” high on customization and “buy” high on time-to-value, then average the scores and call it a tie. A tie is not a decision. If the scores are close, default to the option with the lower switching cost.

When buying is the right call

Buy when the capability is well-understood, non-differentiating, and expensive to operate. Classic examples for API-focused teams:

• Error tracking and observability — unless your product is an observability tool, you are not adding value by maintaining your own exception tracker.
• Billing and subscription management — tax compliance alone justifies the purchase for most teams.
• Email and notification delivery — deliverability is a specialized operational problem.
• Identity and access management — the security surface is too large to own casually.

In these cases, the vendor’s entire business is the problem you are trying to solve on the side. Your team’s time is better spent on the API surface your customers actually pay for.

When building is the right call

Build when the capability is tightly coupled to your domain model or your delivery guarantees. For example:

• Webhook delivery infrastructure — if your customers depend on exactly-once or at-least-once semantics with your specific retry policy, a generic vendor will not match.
• SDK generation from your OpenAPI spec — the generator is a commodity, but the ergonomics and language-specific conventions are your developer experience.
• Internal documentation systems tied to your API lifecycle — if docs must reflect the current API version automatically, a static site generator plus your own pipeline may be simpler than a vendor platform.

The pattern: build when the thing is load-bearing for your product’s contract with developers. Buy when the thing is supporting infrastructure that many companies need and few differentiate on.

The hidden cost nobody puts in the spreadsheet

Both options have a cost that rarely appears in the decision matrix: cognitive load. An internal service adds another thing your team must understand during incidents. A purchased tool adds another vendor relationship, another login, another support channel, and another set of release notes to track.

For a team of 20–200 developers, the number of tools matters. Each tool is a context switch. Each internal service is a page in the on-call runbook. The best build-versus-buy decision is often the one that reduces the total number of systems your team must hold in their heads at 2 a.m.

This is why “we can build it in a weekend” is not a sufficient argument. The weekend build becomes a permanent resident of your architecture. The question is not whether you can build it. The question is whether you want to own it.

A worked example: webhook retry infrastructure

Suppose your team needs to deliver webhooks with retries and signature verification. A vendor offers a managed webhook gateway. Your team could also build a small service on top of your existing queue.

Build analysis: You already have a queue and a worker pool. The service needs a retry policy, a dead-letter queue, and a signature scheme. That is a few weeks of work. But your customers expect webhooks to be delivered within 500 milliseconds, and the vendor’s average latency is 2 seconds. The vendor also does not support your custom event ordering guarantees.

Buy analysis: The vendor handles retries, backoff, and delivery logs. But you would need to change your event schema to match their payload format. Your existing consumers would need a migration. The vendor’s signature verification uses a different algorithm than the one your SDKs already implement.

In this case, the integration surface is the deciding factor. The build wins because the cost of adapting your contracts to the vendor exceeds the cost of building the retry logic you already understand.

Before/after: the decision document

Most teams make the decision in a meeting and then forget the reasoning. Six months later, someone asks “why did we build this?” and nobody remembers. Write a one-page decision document. It does not need to be long.

Before (vague):

We decided to build the webhook service because the vendor was too expensive.

After (specific):

Decision: Build webhook delivery in-house.
Date: 2025-03-14
Alternatives considered: Vendor A, Vendor B
Deciding factors:
- Vendor A could not meet our 500ms delivery target (measured 2s average).
- Vendor B required a payload schema change affecting 3 existing consumers.
- Our retry semantics are already implemented in the queue layer.
Estimated build time: 3 weeks.
Estimated annual maintenance: 0.5 FTE.
Switching cost if we change later: Low; the service is isolated behind an internal interface.
Owner: Platform team.
Review date: 2026-03-14.

The “after” version gives the next engineer enough context to revisit the decision without relitigating it. That is the difference between a decision and a rumor.

Common failure patterns

Watch for these in your own discussions. They are reliable predictors of regret.

The demo-driven decision

A vendor demo shows the happy path in a clean environment. Your production environment has edge cases. Before buying, ask for a trial that includes your actual payloads, your actual error rates, and your actual authentication flow. If the vendor cannot support a trial, that is information.

The resume-driven build

An engineer wants to build something interesting. The business need is secondary. This is not always wrong — sometimes the interesting build is also the right build — but the decision document should name the actual business reason. If the only reason is “it would be fun to build,” that is a hobby, not a strategy.

The sunk-cost spiral

A team has already spent three months on an internal build. It is not working. The rational move is to stop and buy. The emotional move is to spend three more months proving the first three were not wasted. The decision framework should include a kill criterion: “If we have not shipped a usable version by [date], we will revisit the buy option.”

How this connects to API design

Build-versus-buy decisions are API design decisions in disguise. Every purchased tool that touches your API surface introduces a dependency. Every internal service you build becomes part of your API’s operational contract. The question is not “which option is cheaper?” but “which option keeps our API predictable for the developers who depend on it?”

For teams that treat their API as a product, the answer is usually: buy the boring infrastructure, build the parts that define your developer experience. The boring infrastructure is where vendors compete on price and reliability. The developer experience is where your team’s judgment matters.

FAQ

How do we decide when the team is split?

Do not vote. Assign a single decision owner and require a written decision document. The owner must name the deciding factor, not just the preference. If the deciding factor is disputed, test it with a time-boxed spike or a vendor trial. Split teams usually disagree about facts, not preferences. Find the fact.

What is a reasonable time-box for a build-versus-buy evaluation?

Two weeks for most decisions. If the evaluation takes longer, the team is probably comparing features instead of constraints. The goal is not to know everything; it is to know the two or three things that actually determine the outcome. Write those down and stop researching.

Should we revisit past build-versus-buy decisions?

Yes, on a schedule. Put a review date in the decision document. A tool that was right two years ago may be wrong now. A service that was cheap to build may be expensive to maintain. The review does not need to be a big project; a one-hour check against the original deciding factors is enough.

What if the vendor goes out of business or gets acquired?

This is a real risk, especially for smaller vendors. Ask about data export before you sign. Ask what happens to your data if the contract ends. If the vendor cannot answer clearly, treat that as a switching-cost problem. The decision matrix already includes switching cost; this is where it pays off.

Next step: If your team is currently debating a build-versus-buy decision, start with the three-question filter and the one-page matrix. The decision document template above is enough to get started. The goal is not a perfect process; it is a decision you can explain six months later without embarrassment.

API versioning is the practice of labeling and managing changes to an API’s contract so existing clients keep working while new capabilities ship. Adjacent concepts include backward compatibility, deprecation policy, semantic versioning, and change management. For teams with 20–200 developers, versioning is not a ceremony: it is the difference between a platform that evolves and one that quietly breaks integrations every quarter. Most strategies I see are backwards because they optimize for the producer’s convenience, not the consumer’s reality.

Here is the uncomfortable truth: if your versioning strategy starts with “we’ll just put /v2 in the URL,” you have already skipped the hard part. The hard part is deciding what a breaking change actually is, who gets to make one, and how long the old contract lives. This article is a practical, no-nonsense look at why common versioning advice fails, what to do instead, and how to make a decision you can defend in an incident review.

The Backwards Default: Versioning as a Routing Hack

Most teams treat versioning as a routing problem. Add /v1 or /v2 to the path, duplicate the controller, and move on. This feels productive because it is visible. The URL changes, the OpenAPI spec gets a new entry, and the release notes say “v2 released.”

The problem is that path-based versioning encodes the wrong thing. It says: “This is a different resource,” when what you usually mean is: “This is the same resource with a different shape.” Clients now have to know which URL to call, and your routing table becomes a museum of past mistakes. Worse, path versioning encourages teams to create a new version for changes that are not breaking at all, because it is easier than doing the compatibility work.

What “Backwards” Looks Like in Practice

Here is a before-and-after example from a typical REST API. The team wants to rename user_name to display_name.

Backwards approach:

GET /api/v1/users/42
{
  "user_name": "priya"
}

GET /api/v2/users/42
{
  "display_name": "priya"
}

Better approach:

GET /api/users/42
{
  "user_name": "priya",
  "display_name": "priya"
}

The better approach adds the new field, keeps the old one, and documents a deprecation date. No new URL, no new client work, no routing table explosion. The backwards approach creates a parallel universe for a rename that could have been a non-breaking addition.

The Real Unit of Versioning Is the Contract, Not the URL

A version is a promise about behavior. The promise includes request and response shapes, error semantics, rate limits, and side effects. When you change any of those in a way that breaks a reasonable client, you have a new version. The URL is just one place to express that version.

This is why I prefer content negotiation or header-based versioning for most internal and partner APIs. The resource stays stable; the representation changes. It forces you to think about what the client actually accepts, not what path they memorized.

Decision Matrix: When to Use Which Versioning Style

None of these are universally correct. The point is to choose based on who consumes the API and how they discover changes, not based on what your framework makes easiest.

Deprecation Is the Strategy; Versioning Is the Tactic

Most teams treat deprecation as an afterthought. They ship v2, add a note that v1 “will be removed soon,” and then never remove it. Three years later, v1 is still running, v2 has its own quirks, and nobody knows which one is canonical.

A sane deprecation policy has three parts:

• Announcement: a dated, public notice that a field, endpoint, or behavior is deprecated.
• Sunset window: a fixed period, usually 6–12 months for public APIs, during which the old contract still works.
• Removal: a hard cutoff with monitoring to catch stragglers.

If you cannot commit to all three, do not deprecate. Just keep the old field forever and document it as legacy. A permanent legacy field is less harmful than a “deprecated” field that never dies, because at least the status is honest.

Checklist: Is This Change Breaking?

Use this checklist before you reach for a new version number:

• Are you removing a field that clients might read? Breaking.
• Are you changing a field’s type or format? Breaking.
• Are you adding a required request field? Breaking.
• Are you changing an error code or status code for the same situation? Breaking.
• Are you adding a new optional field? Not breaking.
• Are you adding a new endpoint? Not breaking.
• Are you changing rate limits? Usually breaking for clients that relied on the old limit.

If you answer “breaking” to any of these, you have a versioning decision. If you answer “not breaking” to all of them, you have a normal release. The backwards strategy is to treat every change as a version bump because it is easier than doing the analysis.

Webhooks Make Versioning Visible

Webhooks are where versioning mistakes become customer-facing incidents. A webhook payload is a contract you push to someone else’s server. They cannot change their parser as fast as you can change your emitter.

The practical rule: include a version field in every webhook payload, and never change the meaning of an existing version. If you need to change the payload shape, emit a new version and let consumers opt in. This is not theoretical. Stripe, for example, uses event schema versions and API versions together, and their documentation is explicit about how long old versions remain supported.

For internal webhooks, the same rule applies. The team that owns the consumer may be two desks away, but they still need a migration window. A webhook without a version field is a future incident with a timestamp.

SDK Generation Changes the Math

If you generate SDKs from an OpenAPI spec, versioning decisions leak into code generation. A path-based version like /v2 often becomes a separate client class or namespace. That is fine if the change is truly breaking. But if you version for a non-breaking addition, you now have two SDKs for one API, and users have to know which one to import.

The better pattern is to keep operation IDs stable and use the spec’s deprecated flag on fields and operations. Code generators can then produce deprecation warnings in the SDK, which is a much gentler migration path than a new major version.

Before/After: OpenAPI Deprecation

Before:

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

After:

paths:
  /users/{id}:
    get:
      operationId: getUser
      deprecated: false
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: include_legacy_fields
          in: query
          required: false
          schema:
            type: boolean
            default: false
          deprecated: true

The after version keeps the operation ID stable, adds a deprecated query parameter for legacy clients, and gives SDK users a compiler warning instead of a breaking import change.

Why “Just Use GraphQL” Is Not a Versioning Strategy

GraphQL advocates sometimes claim that GraphQL solves versioning because clients request exactly the fields they need. That is true for additive changes. It is not true for removing a field, changing a field’s type, or changing the semantics of a resolver. Those are still breaking changes, and GraphQL’s answer is usually “don’t do that” or “use a new field name.”

For REST APIs, the same discipline applies: add new fields, never remove old ones without a deprecation window, and treat semantic changes as breaking. The difference is that REST makes the contract explicit in the URL and status codes, while GraphQL hides it in the schema. Neither approach saves you from thinking about compatibility.

A One-Week Action Plan

Here is something you can do this week, not next quarter:

1. Pick one public or internal API your team owns.
2. List every field, endpoint, and error code that has changed in the last 12 months.
3. Mark each change as breaking or non-breaking using the checklist above.
4. For each breaking change, write down what the versioning strategy actually was. If the answer is “we added /v2 and hoped,” you have found the problem.
5. Draft a one-page deprecation policy: announcement channel, sunset window, removal criteria.
6. Share it with the team that consumes the API. Ask them what would make migration easier.

That is six steps. None of them require a new framework or a re-architecture. They require you to look at the contract from the consumer’s side, which is the only side that matters.

FAQ

What is the most common API versioning mistake?

The most common mistake is using a new URL version for changes that are not breaking. This creates parallel APIs, confuses clients, and makes deprecation harder. The fix is to classify changes as breaking or non-breaking before deciding on a version.

Should I use URL, header, or query parameter versioning?

It depends on your consumers. For public APIs with unknown clients, URL or query parameter versioning is more visible and cacheable. For internal APIs with a few known consumers, header-based versioning or content negotiation reduces URL churn. For webhooks, put the version in the payload itself.

How long should I support an old API version?

A common sunset window is 6–12 months for public APIs, but the right answer depends on your consumers’ release cycles. The key is to announce the deprecation with a specific date, monitor usage, and actually remove the old version when the window closes. A permanent legacy field is better than a “deprecated” field that never dies.

Does semantic versioning apply to REST APIs?

Semantic versioning is useful for libraries and SDKs, but it maps awkwardly to REST APIs because the “major version” is often expressed in the URL or header. The principles still apply: breaking changes require a new major version, additive changes do not. The mistake is treating every release as a major version bump.

Next up on the blog: a practical guide to writing deprecation notices that engineers actually read. If you have a versioning horror story, send it in — the best one gets a dry, sympathetic response.

Developer onboarding is the process of getting a new engineer from “signed offer” to “shipping useful code with confidence.” It sits at the intersection of engineering culture, internal documentation, and API design. If your product exposes REST APIs, webhooks, or generated SDKs, onboarding is also where new hires learn whether your developer experience is real or just a slide deck. For teams of 20–200 developers, a bad onboarding process compounds quietly: every new hire spends weeks flailing, senior engineers burn hours answering the same questions, and your internal docs slowly become fiction. This article is a practical guide to fixing that.

Most onboarding advice is either HR theater or a list of tools. What actually works is treating onboarding like an API: a stable contract between the new hire and the team, with clear inputs, predictable outputs, and versioned documentation. The goal is not to make someone feel welcome. The goal is to make them productive without making them feel stupid.

Why Most Developer Onboarding Fails

The typical failure mode is not a lack of effort. It is a lack of structure. A new hire gets a laptop, a wiki link, and a Slack channel. Then they spend three days trying to get the local environment running because the README says “install dependencies” but not which ones, or why, or what to do when the build fails on a missing system library.

Here is the uncomfortable truth: if your onboarding depends on tribal knowledge, you do not have onboarding. You have a hazing ritual with extra steps.

Common failure patterns include:

• The documentation mirage: Docs exist, but they were written by someone who left 18 months ago and describe a version of the system that no longer exists.
• The hero dependency: One senior engineer knows how everything works. They are also the person who reviews every pull request, so they have no time to explain anything.
• The sink-or-swim sprint: The new hire is assigned a real ticket in week one. They either figure it out or drown quietly.
• The tool overload: Fifteen different systems, each with its own login, VPN, and two-factor setup. Nobody knows the order in which to request access.

None of these are fixed by buying more software. They are fixed by treating onboarding as a designed system with a measurable outcome.

Define the Onboarding Contract

Before you write a single doc, decide what “done” means. A useful onboarding contract has three parts:

1. Day-one outcome: The new hire can run the codebase locally and make a trivial change.
2. Week-one outcome: The new hire has shipped a small, low-risk change to production.
3. Month-one outcome: The new hire can explain the system architecture and has contributed to at least one API endpoint or webhook handler.

These outcomes are not aspirational. They are testable. If a new hire cannot reach the week-one outcome, the onboarding process is broken, not the new hire.

Write the contract down

Put the contract in your internal docs, not in a manager’s head. A simple table works:

This is not bureaucracy. It is a shared definition of success. Without it, every onboarding conversation becomes a debate about whether the new hire is “doing fine.”

Build a Runbook, Not a Wiki

A wiki is a graveyard of good intentions. A runbook is a sequence of steps that someone actually follows. The difference is that a runbook is tested by a real human on a regular basis.

Your onboarding runbook should cover:

• Access requests: Which systems need accounts, who approves them, and how long it takes. Include the order of operations. If you need a VPN before you can request GitHub access, say so.
• Environment setup: Exact commands, not prose. If a command fails, include the known error and the fix.
• Codebase tour: A map of the repository, not a 40-page architecture document. Point to the API routes, the webhook handlers, and the SDK generation scripts.
• First task: A small, well-scoped ticket that touches a real code path. The ticket should have a clear acceptance criterion and a link to a similar past change.

Test the runbook on every new hire

Here is the rule: if a step in the runbook fails for a new hire, the runbook is wrong. Not the new hire. Fix the runbook immediately. This is the same principle as a failing test: the test is the source of truth, and the code must change.

One practical trick: have the onboarding buddy follow the runbook themselves on a fresh machine once per quarter. If they cannot complete it, neither can a new hire.

Use Your Own API as the First Lesson

If your company builds REST APIs, the best onboarding exercise is to make the new hire consume your own API. Not read about it. Use it.

Give them a task like this:

Create a new resource via the REST API, then set up a webhook to receive an event when that resource changes. Write a short note on what surprised you.

This does three things at once:

1. It teaches the new hire how your product actually works.
2. It exposes gaps in your API documentation and developer experience.
3. It creates a natural first contribution: fixing the docs or the API ergonomics.

If your API is painful for a new hire, that is not an onboarding problem. That is a product problem. Onboarding just made it visible.

Before and after: a first-task example

Here is a typical bad first task:

// Bad: vague, requires tribal knowledge
// Ticket: "Fix the webhook retry logic"
// No context, no acceptance criteria, no pointer to relevant code

Here is a better version:

// Good: scoped, testable, with a pointer
// Ticket: "Webhook retries should use exponential backoff"
// Context: See docs/webhooks.md for current behavior.
// Acceptance: Add a test that verifies retry delays are 1s, 2s, 4s, 8s.
// Pointer: See src/webhooks/retry.ts and tests/webhooks/retry.test.ts

The difference is not effort. It is respect for the new hire’s time.

Assign an Onboarding Buddy Who Is Not the Manager

The manager should own the contract. The buddy should own the daily friction. A good buddy is someone who has been at the company for at least six months, is not the new hire’s manager, and has enough patience to answer the same question twice.

Buddy responsibilities should be explicit:

• Meet daily for the first week, then every other day for the second week.
• Review the new hire’s first pull request before anyone else.
• Walk through the runbook together on day one.
• Escalate anything that blocks the new hire for more than an hour.

This is not a mentorship program. It is a support role with a defined end date. After two weeks, the buddy goes back to their normal work.

Make Internal Documentation Part of the Job

Onboarding exposes documentation rot faster than any audit. The fix is not to hire a technical writer. The fix is to make documentation a first-class part of engineering work.

Three rules that work:

1. Docs live next to code. If a behavior changes, the doc changes in the same pull request.
2. Every runbook has an owner. If the owner leaves, the runbook is reassigned, not orphaned.
3. New hires update the runbook during onboarding. If they find a broken step, they fix it. This is their first contribution.

This creates a feedback loop: onboarding improves documentation, and documentation improves onboarding. The alternative is a wiki that everyone ignores until the next new hire arrives.

Measure Onboarding Without Making It Weird

You do not need a dashboard. You need three numbers:

• Time to first merged pull request. If this is more than five working days, something is wrong.
• Time to first production deployment. If this is more than two weeks, the deployment process is too complex.
• Number of runbook fixes per new hire. If this is zero, either the runbook is perfect or nobody is reading it. It is never perfect.

Track these numbers in a spreadsheet. Review them quarterly. Do not turn onboarding into a performance metric for the new hire. It is a metric for the team.

What to Do This Week

You do not need a committee or a six-month plan. Do this instead:

1. Pick one recent new hire. Ask them what the three most confusing parts of their first week were.
2. Open your onboarding runbook. If you do not have one, write the first draft today. It can be 20 lines.
3. Find the one step that most often fails. Fix it. Then add a note to the runbook explaining the fix.
4. Assign an onboarding buddy for the next new hire. Tell them what the role means.

That is it. Onboarding is not a project. It is a habit.

FAQ

How long should developer onboarding take?

For a mid-to-senior engineer at a company with 20–200 developers, expect meaningful productivity within two to four weeks. The first merged pull request should happen within the first week. Full architectural fluency takes longer, but the goal of onboarding is not mastery. It is unblocked contribution.

What is the difference between onboarding and orientation?

Orientation is administrative: HR forms, benefits, security training. Onboarding is technical and social: learning the codebase, the API design conventions, the deployment process, and the team’s communication norms. Orientation should take hours. Onboarding takes weeks.

Who should own the onboarding process?

The engineering manager owns the contract and the outcomes. An onboarding buddy owns the daily support. The new hire owns their own learning. If any one of those three roles is missing, the process breaks.

How do you onboard a remote developer effectively?

The same principles apply, but the runbook must be more explicit. Remote hires cannot tap a neighbor on the shoulder. Schedule daily check-ins for the first week, record environment setup sessions, and make sure every access request has a documented owner and expected turnaround time.

What if our internal documentation is already a mess?

Start with the runbook, not the wiki. A runbook is a single path through the mess. You do not need to fix all documentation. You need one reliable path for a new hire to follow. Fix the rest incrementally as new hires hit broken links.

Next up on this site: a look at how to write API reference docs that new hires actually read, and why most generated docs fail the “can I use this without asking a human?” test.

Technical debt is the accumulated cost of expedient engineering decisions that make future change slower, riskier, or more expensive. It lives in undocumented endpoints, inconsistent error contracts, hand-rolled SDKs that drift from the API, and webhook handlers that fail silently. For teams of 20–200 developers, technical debt is not a moral failure. It is a business liability with a measurable interest rate. This article is about naming that rate, deciding when to pay it down, and avoiding the most expensive forms of debt in REST APIs, webhooks, SDKs, and internal documentation.

Most engineering teams do not lack awareness of technical debt. They lack a shared vocabulary for its cost. One developer calls a workaround “temporary.” A product manager calls it “shipped.” Six months later, an incident calls it “the reason we missed the deadline.” The goal here is practical: give you a way to price debt, prioritize it, and explain the tradeoff without a slide deck full of metaphors.

What Technical Debt Actually Costs in an API-First Team

Technical debt is not the same as bad code. Bad code is code that never should have shipped. Technical debt is code that shipped for a reason: a deadline, a missing dependency, an unclear requirement, a customer escalation. The debt is the difference between what the code is and what it should be, given what the team now knows.

In API design, the most common forms of debt are:

• Contract drift: the OpenAPI spec says one thing, the implementation does another, and the SDK was generated from a third source.
• Inconsistent error handling: some endpoints return application/problem+json, others return a bare 500 with an HTML body.
• Webhook retry gaps: the system retries on network failure but not on 4xx responses, so a bad payload silently disappears.
• Documentation rot: the internal docs describe version 2 of the API while production runs version 4.
• SDK drift: the generated client is six months behind the API, and one team has patched it locally in ways nobody else knows about.

Each of these has a different interest rate. Contract drift is expensive because every integration team pays it. Inconsistent errors are expensive because every support ticket pays it. Webhook gaps are expensive because they fail in production, not in review. Documentation rot is expensive because it taxes every new hire and every cross-team review.

The Interest Rate Is Paid in Review Time, Not Just Incidents

When people talk about technical debt, they usually point to outages. But the larger cost for a mid-sized engineering organization is slower review cycles and higher cognitive load. A developer who must check three sources to learn how an endpoint behaves is paying interest on every task. A reviewer who cannot trust the spec is paying interest on every pull request. A support engineer who cannot reproduce a webhook failure is paying interest on every ticket.

This is why technical debt in API design is more dangerous than technical debt in a single service. A messy internal function costs the team that owns it. A messy public contract costs every team that consumes it, including teams outside your company.

How to Price Technical Debt Without a Spreadsheet Religion

You do not need a formal cost-of-delay model to make good decisions. You need three questions:

1. Who pays the interest? One team, all internal consumers, or external customers?
2. How often is the interest paid? Every deploy, every review, every new integration, or only during rare incidents?
3. What is the cost of not paying now? Will the debt compound, or will it stay flat until the next major version?

Here is a simple decision matrix that works for most API teams:

The point of the matrix is not precision. It is to stop treating all debt as equal. A legacy endpoint with no consumers is not debt. It is a museum exhibit. A documented but awkward internal helper is debt with a low interest rate. An undocumented public endpoint is debt with a credit card APR.

Where API Teams Accumulate the Most Expensive Debt

1. Error Contracts That Evolve by Accident

Most REST APIs start with a clear error format. Then someone adds a validation error that does not fit. Then a gateway adds its own error shape. Then a webhook handler returns a 200 with an error body because the retry logic was misconfigured. Within a year, the API has four error formats and no single source of truth.

The fix is not a grand error-handling framework. It is a written contract and a test that enforces it. For example:

// Before: error shape depends on which layer caught the failure
{ "message": "Invalid input" }
{ "error": "validation_failed", "details": [...] }
{ "status": 400, "title": "Bad Request" }

// After: one contract, enforced in CI
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/v1/users",
  "errors": [
    { "field": "email", "issue": "invalid_format" }
  ]
}

The before/after is not about aesthetics. It is about whether a support engineer can write a single troubleshooting guide or needs a decision tree for every endpoint.

2. Webhooks That Fail Silently

Webhooks are the most common place for technical debt to hide because failures are asynchronous and often invisible to the producing team. A webhook that returns 200 on a malformed payload is not a success. It is a lost event with a receipt.

The expensive version of this debt looks like:

• No retry policy, or a retry policy that only covers network timeouts.
• No idempotency key, so a retry creates duplicate side effects.
• No dead-letter queue, so failed deliveries vanish after N attempts.
• No signed payloads, so consumers cannot distinguish a real event from a spoofed one.

The cheap version is a documented delivery contract: what gets retried, how many times, with what backoff, and what happens after the final attempt. That contract is not a feature. It is the difference between a webhook and a hope.

3. SDKs That Are Generated but Not Governed

SDK generation is a force multiplier until it is not. The moment a team patches a generated client by hand, the generator becomes a suggestion. The next regeneration overwrites the patch, or the patch survives and the generator output diverges. Either way, the SDK is now a fork with no owner.

The debt prevention rule is simple: if you generate an SDK, you must own the generator pipeline. That means versioning the generator, testing the output, and treating hand-edits as a build failure. If a hand-edit is truly necessary, the fix belongs in the generator or the API spec, not in the generated code.

4. Internal Documentation That Describes the Past

Internal documentation is the most socially acceptable form of technical debt. Nobody gets fired for writing a wiki page. But a wiki page that describes an API from two versions ago is worse than no page at all, because it creates false confidence.

The practical fix is to make documentation a build artifact, not a writing assignment. If your API spec is the source of truth, generate the reference docs from it. If your webhook contract lives in a schema, publish the schema. The less documentation that requires a human to remember to update it, the less debt you accumulate.

When Not to Pay Down Technical Debt

Some debt should be left alone. The discipline is knowing which.

Do not refactor code that is about to be deleted. If an endpoint is deprecated and its last consumer is migrating next quarter, refactoring it is a waste. Write the deprecation notice, set the sunset date, and move on.

Do not pay down debt in a system you do not understand. A legacy service with no tests and no owner is not a refactoring project. It is an archaeology project. The first payment is characterization tests, not cleanup.

Do not let debt repayment block a security fix. If a vulnerability requires a breaking change, ship the breaking change. Debt can wait. Exploits cannot.

The common thread is that debt repayment is a prioritization decision, not a virtue. A team that refactors everything is as ineffective as a team that refactors nothing.

A One-Week Action Plan

Here is a concrete step you can take within a week, no committee required:

1. Pick one public or internal API surface that your team owns.
2. List every consumer of that surface: internal services, SDK users, webhook subscribers, support tooling.
3. Find one inconsistency that costs consumers time: an undocumented field, an error shape mismatch, a missing retry policy.
4. Write the fix as a contract change, not a code change. Update the spec, the schema, or the runbook first.
5. Add a test or CI check that fails when the contract drifts again.

That is the whole exercise. It will take less than a week and will reveal more about your debt than a quarter of architectural review meetings.

Frequently Asked Questions

What is the difference between technical debt and bad code?

Bad code is code that should not have shipped. Technical debt is code that shipped for a legitimate reason but now costs more to change than it should. The distinction matters because bad code is a quality problem, while technical debt is a tradeoff problem. You fix bad code. You manage technical debt.

How do you measure technical debt in an API?

Measure it by the cost it imposes on consumers. Count the number of undocumented fields, inconsistent error shapes, missing retry policies, or SDK versions behind the API. Then estimate how often each one costs a developer or support engineer time. The unit is not “lines of code.” It is “minutes per integration.”

When should technical debt be paid down versus accepted?

Pay down debt when the interest rate is high: many consumers, frequent use, or a public contract. Accept debt when the interest rate is low: one internal consumer, rare use, or a system nearing deprecation. The decision matrix earlier in this article is a practical starting point.

Does SDK generation eliminate technical debt?

No. SDK generation moves the debt from the client code to the generator pipeline. If the pipeline is unowned, unversioned, or allows hand-edits, the debt returns in a harder-to-find form. Generation is only a debt reduction when the pipeline is treated as a first-class product.

What is the most overlooked form of technical debt in API teams?

Silent webhook failures. Because webhooks are asynchronous and often owned by the producing team, failed deliveries can go unnoticed for months. A webhook that returns 200 on a malformed payload is a lost event with a receipt, and it is usually discovered by a customer, not by monitoring.

What Comes Next

This article is part of a longer conversation about API maintainability. A natural follow-up is a deep look at error contract design across REST APIs and webhooks, including a reference implementation you can adapt. If you have a specific debt story from your own API surface, the comments are open. The best next article usually comes from a reader question.

Technical debt works like a high-interest credit card you forgot you signed up for. You ship the feature on time, everyone’s happy, and then the interest kicks in—every future change costs a little more. For teams running REST APIs, that interest shows up as mismatched resource shapes, ghost endpoints nobody documented, and the one POST handler that’s become a folk legend because touching it breaks production in ways nobody can explain. The price isn’t just the extra hours spent untangling old code. It’s the pull requests that stall out, the SDKs that trail the API by three releases, and the slow-motion trust collapse between the frontend and backend groups.

This piece is for the engineering lead who can feel the drag but can’t put a number on it, and for the senior dev who spends more time explaining the API than actually building it. We’ll dig into what technical debt really costs in a REST API context, how to spot the expensive kind, and—most usefully—how to start paying it down without betting the farm on a six-month rewrite.

What Technical Debt Actually Means for an API

Ward Cunningham gave us the metaphor back in ’92, but inside a REST API, technical debt has its own particular stink. It’s not just messy code. It’s the gap between the API you’ve built and the API your consumers think they’re calling. You measure that gap in support tickets, busted SDK implementations, and the slow creep of “special case” logic that makes every new endpoint take twice as long as the last one.

In a mid-sized shop—say, 20 to 200 developers—the API is the central nervous system. When its design rots, the symptoms spread. Mobile teams build workarounds. Frontend teams lean on aggressive caching to hide latency from bloated payloads. Backend teams duplicate endpoints because modifying the original feels like defusing a bomb. The debt isn’t just in the code. It’s in the team’s shared understanding, or the lack of one.

How to Spot the Debt That Actually Matters

Not all technical debt is created equal. A slightly inconsistent naming convention on an internal-only endpoint is a paper cut. A missing pagination scheme on a list endpoint that happily returns 10,000 records is a hemorrhage. Here’s a decision matrix to help you triage.

Structural and contractual debt are the killers. They force every consumer of your API—including your own frontend team—to write defensive code that assumes nothing. That defensive code becomes its own layer of debt, and the cycle accelerates.

The Hidden Tax: Developer Experience Decay

When we talk about API technical debt, we usually fixate on the server side. But the real cost often shows up in developer experience (DX). A poorly maintained API leaks time in ways that don’t appear on a Jira board.

Consider a team building an SDK for your API. If the OpenAPI specification is hand-written and hasn’t been updated in three releases, the SDK team either generates broken code or writes the client by hand. Both options are expensive. The generated code ships with bugs that get reported back to the API team. The hand-written client diverges from the actual API, creating a parallel maintenance burden. Either way, the debt on the server side has now metastasized to the client side.

This is why internal documentation systems—the kind that auto-generate from source-of-truth specs—are not a luxury. They’re a hedge against this exact type of compounding debt. When your OpenAPI spec is the source of truth, and your documentation, SDKs, and even your integration tests are generated from it, a single fix propagates everywhere. Without that, you’re manually patching the same leak in five different places.

Webhooks: The Debt You Don’t See Until It Breaks

Webhooks are particularly dangerous because they invert the control flow. With a REST endpoint, you can version the URL, add deprecation headers, and give consumers a migration path. With webhooks, you’re pushing data into someone else’s system. If you change the payload shape without warning, you’ve broken their integration—and they might not notice until a critical workflow fails.

Common webhook debt patterns include:

• Payload drift: The webhook body no longer matches the documented schema because someone added a field to the internal event model and forgot about the webhook serializer.
• Missing delivery guarantees: The system fires a webhook once and forgets it. No retry, no logging. When a subscriber’s endpoint is down, the event is simply lost.
• Signature rot: The signing secret was rotated in the API but not updated in the webhook configuration, so all signatures fail validation on the consumer side.

Fixing webhook debt requires a different approach than REST endpoint debt because you can’t just version the payload and call it a day. You need a deprecation policy that includes a communication channel—email, dashboard notification, or a dedicated /webhook-changelog endpoint—so consumers know what’s coming before it breaks them.

Before/After: Refactoring a Debt-Heavy Endpoint

Let’s look at a concrete example. Here’s a simplified but realistic endpoint for listing orders, written under time pressure:

Before: The “Just Ship It” Version

GET /api/orders
Response 200:
{
  "orders": [
    {
      "id": 4821,
      "cust": "acme-corp",
      "total": "149.99",
      "status": 2,
      "items": [
        {"sku": "WID-001", "qty": 2, "price": "49.99"}
      ]
    }
  ]
}

What’s wrong here? The field names are abbreviated and inconsistent (cust vs. id). The total and price are strings, forcing every client to parse floats. The status is a magic integer. There’s no pagination, so this endpoint will eventually time out. And the response wrapper is an object with a single key—why not just return an array? (Because you can’t add metadata to an array later without a breaking change. But the team didn’t add metadata, so the wrapper is just dead weight.)

After: A Maintainable, Self-Describing Response

GET /api/orders?page=1&per_page=50
Response 200:
{
  "data": [
    {
      "id": "ord_4821",
      "customer": {
        "id": "cust_acme-corp",
        "name": "Acme Corp"
      },
      "total": {
        "amount": 149.99,
        "currency": "USD"
      },
      "status": "shipped",
      "items": [
        {
          "sku": "WID-001",
          "quantity": 2,
          "unit_price": {
            "amount": 49.99,
            "currency": "USD"
          }
        }
      ],
      "created_at": "2025-01-15T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 142,
    "next": "/api/orders?page=2&per_page=50"
  }
}

The refactored version uses consistent, descriptive field names, proper number types, string enums for status, and a pagination envelope. The data wrapper now earns its keep by sitting alongside pagination metadata. A client can consume this without reading external docs—the response teaches you how to use it.

Why “We’ll Document It Later” Is a Lie

Every engineering team has a graveyard of good intentions. The out-of-date wiki. The Confluence page last edited 18 months ago. The README that says “coming soon.” In API work, documentation debt is especially corrosive because it breaks the feedback loop between the team building the API and the teams consuming it.

When documentation is a separate, manual step, it’s the first thing dropped under schedule pressure. The result: your API’s actual contract becomes whatever the code happens to return. Consumers learn by inspecting network traffic, not by reading docs. This is how “unofficial” behavior becomes the de facto standard, and any cleanup risks breaking downstream systems that depend on those undocumented quirks.

The fix is to make the API itself the source of truth. Use your web framework’s serialization layer to enforce response shapes. Generate your OpenAPI spec from that layer, not from handwritten YAML. Then generate your reference docs and SDKs from the spec. When the spec is a build artifact rather than a design document, it can’t fall out of sync—it simply won’t compile if it’s wrong.

Paying Down Debt Without the Big Rewrite

The most dangerous phrase in software is “we’ll fix it in v2.” v2 never ships, or when it does, it carries its own fresh debt because the team tried to fix everything at once. Here’s a safer, incremental approach that works for APIs serving real traffic.

1. Identify the Debt That Hurts Most

Don’t guess. Instrument your API to measure which endpoints generate the most support tickets, have the highest latency, or are most frequently modified. Debt in a high-traffic, high-change endpoint is far more expensive than debt in a stable, internal-only endpoint. Fix the expensive stuff first.

2. Use the Strangler Fig Pattern

For a debt-heavy endpoint, don’t rewrite it in place. Deploy a new, clean endpoint alongside the old one—perhaps under a /v2 path prefix or a new resource name. Route a small percentage of traffic to the new endpoint, monitor for discrepancies, and gradually increase until the old endpoint is idle. Then deprecate and remove it. This is the API equivalent of refactoring behind a feature flag, and it’s far safer than a cutover.

3. Add Deprecation Headers Now, Remove Later

If you have endpoints you know are problematic but can’t yet remove, add a Sunset header and a Deprecation header. The Sunset header tells consumers the date after which the endpoint may disappear. This gives them a deadline and gives you a tool to actually remove it. Without a date, “deprecated” means “we’ll maybe remove this someday,” which means it lives forever.

4. Make Debt Visible in Your Backlog

Create a label for technical debt items and treat them as first-class backlog citizens. During sprint planning, explicitly allocate a percentage of capacity to debt reduction—10% is a common starting point. If every sprint chips away at the pile, the debt stops growing. If you only address debt during “cleanup sprints” that happen twice a year, you’re losing ground.

FAQ

How do I convince my product manager that technical debt work is worth prioritizing?

Frame it in terms of feature velocity, not code quality. Show them data: “Last quarter, 30% of our sprint capacity went to bug fixes and unplanned work related to the orders API. If we spend two weeks cleaning up that endpoint’s debt, we estimate we’ll recover that capacity within six weeks.” Product managers understand capacity and risk. Speak their language.

What’s the difference between technical debt and just bad code?

Technical debt is code that was reasonable when written but has become a liability because the system around it changed. Bad code was never reasonable. The distinction matters because debt implies a deliberate tradeoff—you shipped faster knowing you’d pay later. If you didn’t know you were making a tradeoff, that’s not debt; that’s a skill gap or a process gap. Fix the process first, then the code.

Should we version our entire API or just individual endpoints?

Version at the endpoint level when possible. A global version bump (e.g., /v2/ for everything) forces all consumers to migrate simultaneously, even for endpoints that haven’t changed. Instead, use content negotiation or a custom header to version individual resources. This lets you evolve the API incrementally and reduces the blast radius of breaking changes. If you must use URL-based versioning, do it at the resource level (/v2/orders), not the API root.

How do we handle technical debt in webhook payloads when we can’t version them?

Webhooks don’t have a request-response cycle where you can negotiate a version, so you need a different strategy. First, never remove fields from a webhook payload—only add new ones. Second, include a schema_version field in every webhook body so consumers can branch their parsing logic. Third, maintain a webhook changelog endpoint (GET /webhooks/changelog) that lists every change, when it was deployed, and when old fields will be removed. Give consumers at least 90 days’ notice before removing anything.

What You Can Do This Week

Pick one endpoint that your team complains about—the one that generates the most Slack threads or the most defensive coding. Spend 30 minutes documenting its actual behavior: what it returns, what status codes it uses, what edge cases it handles (or doesn’t). Compare that to what your docs say it does. The gap between those two things is your most expensive debt. Write a one-paragraph summary of that gap and share it with your team. That’s your starting point.

Next week, we’ll look at how to build an internal documentation system that prevents this gap from reopening—using your OpenAPI spec as the single source of truth for docs, SDKs, and integration tests.