API Documentation: Writing for Developers

Good API docs (like Stripe's or Twilio's) are a competitive advantage. They make it easy for developers to "Get to Hello World" in minutes.

The Anatomy of an Endpoint Doc

1. Verb & Path: POST /v1/charges
2. Description: "Creates a new charge for a specific customer."
3. Parameters:
   • amount (Integer, Required): The amount in cents.
   • currency (String, Required): Three-letter ISO code.
4. Response: A JSON object representing the charge.
5. Errors: What happens if the card is declined? (e.g., 402 Payment Required).

Key Vocabulary

• Payload: The data sent in the request body.
• Header: Metadata sent with the request (e.g., Authorization).
• Rate Limit: The maximum number of requests allowed in a time period.
• Deprecation: Warning that an endpoint will be removed in the future.
• Breaking Change: A change that will cause existing integrations to fail.

Writing Style: Imperative & Direct

Use the Imperative Mood for instructions:

• "Pass the API key in the header."
• "Ensure the timestamp is in UTC."
• "Do not share your secret key."

Alex's Tip: Always include a "Troubleshooting" section. List the top 3 most common mistakes developers make when using your API. They will thank you for it!

• I propose we migrate from Jenkins to GitHub Actions. This is expected to cut deploy time to 8 minutes and reduce failure rate below 5%.

The proposal is one clear recommendation, not a menu. Reviewers can challenge it, but they know what you propose.

Alternatives considered

This section is the mark of a thoughtful RFC. Name the other options and why you rejected them:

• Alternative A: Stay with Jenkins and optimize. Rejected: we have tried this; the gains plateau at 25 minutes.
• Alternative B: Move to CircleCI. Rejected: similar cost to GitHub Actions but less integration with our existing GitHub workflow.

Reviewers who preferred an alternative can see you considered it. This builds trust and prevents re-litigating settled points.

Trade-offs

Be honest about what you give up:

• Trade-off: GitHub Actions costs ~$300/month more than Jenkins. We accept this for the speed and reliability gains, which save ~$2,000/month in engineer time.

Honest trade-offs show maturity. Hiding downsides destroys trust when they surface later.

Drive to a decision

An RFC without a deadline drifts. Set a comment deadline:

• Comments due by Friday. I'll make the final call on Monday and we begin the migration next sprint.

This forces a decision. After the deadline, the author (or a decision-maker) finalizes the RFC with the outcome recorded: Decision: Approved. Migration begins sprint 14.

Common mistakes

1. No alternatives. Looks like the decision was assumed, not considered.
2. Hidden trade-offs. Surfacing later breaks trust.
3. No deadline. The RFC drifts; no decision is made.

Practice

Outline an RFC for a decision your team faces:

1. Context (the problem): _
2. Proposal (your recommendation): _
3. One alternative and why rejected: _
4. One trade-off: _
5. Comment deadline: _

In the next lesson, you will learn to write GitHub issues and pull request descriptions.