Writing for APIs: From Reference Docs to Tutorials

Writing for APIs: From Reference Docs to Tutorials

API documentation is the primary interface between your service and developers. Well-structured documentation covers what the API does and how to use it, so that integrators can work with minimal friction. It typically includes available endpoints, parameters (with data types and descriptions), request/response formats, authentication methods, and error handling. Clear, up-to-date docs reduce confusion and accelerate onboarding. Good documentation reduces friction and improves the overall developer experiencet.

Leading developer platforms understand this. For example, Stripe’s API reference has become an industry standard in completeness and clarity. Companies that invest in great docs (like Stripe and Twilio) see faster adoption and fewer support requests. In fact, Stripe’s docs include copy-paste cURL examples and sample JSON responses, and Twilio’s guides walk through code in multiple languages with commentary. This article covers best practices for writing concise yet complete documentation, from detailed reference entries to hands-on tutorials (in the current 2025 context).

1. Writing Clear API Reference (Parameters, Endpoints, and Responses)

Reference documentation should precisely define each API endpoint, its parameters, and expected results. For REST APIs, each entry typically includes:

  • Base URL: Specify the root endpoint (e.g. https://api.example.com/v1) for all calls (include API version if applicable, e.g. /v1). If your API requires authentication, specify the auth method here (API keys, OAuth tokens, etc.) and how to include it (for example, using an Authorization: Bearer <token> header).
  • Endpoint URL and Method: e.g. GET /items/{id}. Describe the full URL pattern and the HTTP method used.
  • Parameter Table: List each parameter’s name, location (path, query, header, or body), type, whether it’s required, and a clear description. Include example or default values where helpful. For example, in an OpenAPI/Swagger spec you might define a path parameter like this: paths: /users/{userId}: get: summary: Get a user by ID parameters: - in: path name: userId schema: type: integer required: true description: Numeric ID of the user to retrieve Here userId has a clear name, type, and description. The Swagger spec requires each parameter entry to include a name, in, schema, and description. Use consistent naming (avoid ambiguous names) and indicate formats or constraints (e.g. YYYY-MM-DD for dates, string length limits).
  • Common Patterns: Document standard API conventions your service uses. For example, explain how pagination works (limit, offset or cursor parameters), how filtering and sorting are done (e.g. ?status=pending&sort=created), or any retry headers.
  • Request Body Schema: If the endpoint accepts a JSON body, document its schema (for example, using JSON Schema or OpenAPI’s requestBody). Specify required fields and data types, and consider including a sample JSON payload.
  • Content Types: Specify the expected request and response media types (e.g. application/json). If your API uses other formats or custom headers (like Content-Type or special versioning headers), document them.
  • Responses: Document possible HTTP status codes and response formats. For each status code (200, 201, 400, 401, 404, 500, etc.), explain the scenario. Always include at least one example response body. For instance, Twilio’s docs show a JSON example when sending an SMS, with fields like "sid", "status", etc. As Stoplight notes, example responses help developers know what to expect.
  • Error Format: If your API returns error information in a JSON (or other structured) payload, describe that format. For example, if errors come back as {"error": {"message": "...", "code": 123}}, include an example error response and explain each field.

Organize the reference for easy scanning. Group related endpoints (for example, put all /users/* endpoints under a Users section) and use clear headings/subheadings. Provide a one-line summary for each endpoint at the top of its entry. The goal is that a developer can quickly find an endpoint and see exactly which parameters it takes and what it returns.

For GraphQL APIs, the documentation focuses on the schema rather than multiple URLs. GraphQL typically uses a single endpoint (e.g. POST /graphql). In your docs, list all Query and Mutation operations (their names) along with their input arguments and return types. Since GraphQL types are self-describing, include each object type and its fields with descriptions. GraphQL supports introspection: clients (and your documentation site) can query special fields (like __schema) to discover types and fields. Mention to developers that tools like GraphiQL or Apollo Explorer use this introspection to browse the API. For example, GitHub’s GraphQL docs show a curl POST for a simple query:

curl -H "Authorization: bearer TOKEN" -X POST \
     -d '{"query": "query { viewer { login } }"}' \
     https://api.github.com/graphql

This fetches the current user’s login. In GraphQL docs, emphasize that fields in the response correspond exactly to the fields in the query. Document the schema’s descriptions so they appear in GraphQL tools (GraphiQL, Playground, etc.), and include both example queries and example JSON responses. (Also, if you maintain versioned GraphQL schemas, note deprecated fields clearly in the docs so clients know what’s changing.)

When writing your OpenAPI specification for a REST API, remember that the spec’s contents become the documentation. Ensure each path and parameter has a clear summary and description. Include example values or JSON schemas in the spec. For instance, an OpenAPI parameter block might look like:

components:
  parameters:
    limitParam:
      in: query
      name: limit
      schema:
        type: integer
        default: 10
      description: Maximum number of results to return

This matches the Swagger pattern of name, in, schema, and description. In the spec’s responses section, list each status code with a description and example schema. A well-annotated OpenAPI file not only helps developers (through auto-generated docs) but also powers tools (e.g. Swagger UI) that generate browsable documentation from it.

2. Using Examples, Use Cases, and cURL Demos

Examples turn abstract documentation into concrete guidance. Every endpoint or feature should be accompanied by practical examples and use cases. The simplest pattern is to show a full curl command and a corresponding example response for each operation:

  • cURL Commands: Show a full curl invocation for common requests, including method, URL, headers, and data. Explain any authentication flags or tokens. For example, Twilio’s SMS tutorial presents exactly how to send a message via curlt: curl -X POST -d "Body=Hello from cURL" \ -d "From=$TWILIO_NUMBER" \ -d "To=$TO_NUMBER" \ "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" This includes all required fields and HTTP Basic Autht. Similarly, Stripe’s reference uses curl examples by default. Such examples let developers copy-paste and run commands immediately. Use backslashes for readability if splitting lines, and provide commentary for non-obvious parts.
  • Sample Responses: After each request example, include the API’s response (typically JSON). For the Twilio example above, a sample JSON response might be: { "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "status": "queued", "to": "+15551234567", "from": "+15557654321", "body": "Hello from cURL" } Highlighting the actual output fields helps developers understand the data structure returned. As Stoplight emphasizes, the response schema is just as important as the request parameters. Even if truncated, showing key fields clarifies integration expectations.
  • Code Snippets (Multiple Languages): If your audience spans multiple programming languages, include short code examples for each major language (Python, JavaScript, Ruby, etc.). These should perform the same action as the curl example. Stripe and Twilio often display multi-language snippets side-by-side. Keep them minimal—just enough to show library usage. Clearly label each snippet with the language and include brief comments. This ensures developers can see how to implement calls in their preferred environment.
  • Use-Case Walkthroughs: Provide examples that solve real problems. For instance, a Stripe guide might walk through creating a customer, then a subscription, step by step, describing each call. A Twilio guide might show sending an email and then parsing the webhook response. Break complex tasks into substeps with headers. Label these clearly (e.g. “Example: Create a New Order”). Embed snippets and explanations in a narrative flow. This contextual approach (often part of a tutorial) helps developers see why they would make certain calls. Treblle specifically advises including “common use cases” in your docs.
  • Error Cases: Include examples of error responses. Show what happens with invalid inputs or missing auth. For example, show a 401 JSON error for an invalid token. Explain the error format (like an "error" object with message and code fields). This helps developers debug integrations faster.
  • Interactive Consoles: If your API or GraphQL has an interactive explorer (e.g. Swagger UI’s “Try it out” or GraphiQL/Apollo Sandbox for GraphQL), mention it. Developers appreciate being able to experiment. For example, GitHub’s GraphQL docs link to its Explorer where users can run queries against the API. You can write: “Try our API using [Live Explorer] or run the following curl command…”

As a rule, make examples copyable and self-explanatory. Use fenced code blocks (bash, json, etc.), and caption them briefly. The industry consensus is clear: documentation should include request/response samples, curl commands, and code for common tasks. Place examples immediately after the related description, and keep them updated. Automation can help: some tools regenerate code samples from spec, but always manually verify them.

3. Reference Docs vs. How-To Guides vs. Tutorials

Complete documentation covers different developer needs. Stoplight frames this as a “continuum from facts to context”. Treblle identifies four types of API docs: Reference Documentation, Tutorials, Quickstart Guides, and Developer/How-To Guides. You should ideally provide all:

  • Reference Documentation (Facts): A complete catalog of endpoints, parameters, schemas, and status codes. This is the static “lookup” material. Developers use it to find exact details (e.g. “what parameters does this endpoint accept?”). Reference docs should be precise, comprehensive, and well-organized. Use tables for parameters, list all error codes, and include examples. Keep the language concise and descriptive (for example, use third person/neutral voice).
  • Quickstart Guides: These are mini-tutorials for first-time users (e.g. “Your First API Call in 5 Minutes”). They get a new user up and running with a basic integration. A quickstart might say “Use curl (or our SDK) to send a Hello World request,” and show exactly how. Quickstarts should assume minimal prior knowledge and highlight the very first steps of setup (API key configuration, importing a library, etc.).
  • How-To Guides (Developer Guides): Step-by-step instructions for specific tasks (like “How to Send an SMS” or “How to Charge a Customer”). They explain why and how to use one or more endpoints in sequence. Each step should include explanation and code. Twilio’s guides do this well, keeping code snippets visible while describing each action. How-to guides often start with a goal (“What you will build”) and conclude with a working example.
  • Tutorials: In-depth walkthroughs that may cover a broader integration or application (for example, building a sample app using the API). These are longer narrative pieces that tie together multiple features or calls. They often include diagrams or screenshots. Tutorials are great for learners to see the “big picture.” For instance, a Stripe tutorial might show integrating checkout into a web app end-to-end, touching both front-end and back-end code.

Each audience segment uses different docs. New developers typically start with a quickstart or tutorial, while experienced users dive into the reference for specifics. The key is to cross-link: reference pages should link to related tutorials, and tutorials should link back to the reference for each endpoint used. As Stoplight stresses, the best docs “nail all three types” of content. By layering reference (details), guides (practical tasks), and tutorials (broader context), you cover both fact-finders and learners.

4. Documentation Formats and Tools: Swagger UI, Postman, and Custom Solutions

After writing content, you must choose how to publish it. Common approaches include:

  • Swagger UI / OpenAPI Tools: If you have an OpenAPI/Swagger specification, tools like Swagger UI or Redoc can generate interactive docs automatically. Swagger UI renders your API spec into a web page where endpoints can be expanded and “try it out” requests can be made. Redoc is another open-source option that produces a clean, three-panel layout from the spec. These are excellent for REST APIs: they keep docs in sync with the spec and often include interactive consoles. In fact, Swagger/OpenAPI is an industry standard (used by over 40% of public APIs) and is ideal for API-first design. A big advantage is SDK Code Generation: Swagger Codegen or OpenAPI Generator can produce client libraries and server stubs in many languages. Postman, by comparison, only provides code snippets and doesn’t generate full SDKs.
  • Postman Documentation: Postman allows you to publish a collection of API calls as documentation. If your team builds or tests APIs with Postman, you can add descriptions and examples to each request and publish it. The Postman Docs feature creates a shareable site listing your endpoints and sample calls. It even supports a “Run in Postman” button so readers can import the collection. Postman is very user-friendly, but its customization options are limited compared to a full portal. It’s best for internal or quick-start publishing. Notably, Postman’s 2025 survey notes that automated or integrated docs keep documentation current and in sync.
  • Custom/Static Documentation Sites: Many companies build bespoke developer portals. This often involves static site generators (like Slate, Docusaurus, Hugo) or CMS platforms. For example, Stripe and Twilio have custom docs sites (Stripe’s is React-based; GitHub’s docs run on Jekyll and are fully open-source). The advantage is full control: you can combine reference, guides, tutorials, changelogs, and even forums in one branded site. You can also integrate search engines or single sign-on for internal docs. The trade-off is engineering effort: as Stoplight notes, building and maintaining a custom site requires significant work. Many teams mitigate this by using documentation frameworks or commercial platforms. For instance, Redocly offers a hosted solution and linting tools, and Stoplight’s platform provides a docs portal from your OpenAPI spec.
  • Search Functionality: Whichever format you choose, ensure the docs are searchable. Developers often search for endpoint names, parameter names, or error codes. Good tools (like Docusaurus or Algolia search) allow full-text search across the docs.

Choosing the right tool: Use Swagger/OpenAPI (and Swagger UI/Redoc) if you want an “always up-to-date” reference with minimal manual maintenance. Use Postman’s docs if you need rapid sharing and integration with API testing. Opt for a custom site if you want a fully polished portal (with tutorials, SDK links, etc.) and have the resources to build it. In practice, many teams use a hybrid: for example, generating the reference from OpenAPI but embedding it in a custom site that also contains guides and tutorials. The content (the writing and examples) is what matters most; the tool should simply present it clearly.

Conclusion

Writing great API documentation is an investment that pays dividends. The best API docs are concise yet complete. Strive for clarity in parameter descriptions and endpoint summaries, but back them with ample examples. Structure your content in layers: a reference for the nitty-gritty details, quickstarts/tutorials for onboarding, and how-to guides for common tasks. Use short paragraphs and bullet lists to make reading easy. Always include sample requests and responses (as Stoplight emphasizes). Provide thorough error and edge-case examples, and make sure to explain authentication and versioning.

Remember these best practices:

  • Be Clear and Consistent: Use simple language, define any jargon, and stick to one terminology. Use active voice and imperative mood in instructions.
  • Document Everything: If it’s part of the API (endpoints, fields, headers, error codes), it should be in the docs. Include schemas, example values, and mandatory vs. optional flags.
  • Use Examples: Liberally use curl snippets, JSON payloads, and code examples. Practical examples and use cases often teach faster than prosetreblle.com.
  • Organize and Navigate: Group related content under clear headings. Provide summaries for each endpoint. Ensure readers can search and find information quickly.
  • Version and Changelog: If you support multiple API versions, separate documentation by version. Maintain a changelog of updates and breaking changes so developers can track the evolution.
  • Metadata and Feedback: Show document last-updated dates and include contact/support info (forum, email, issue tracker). Encourage feedback—GitHub, for example, hosts its docs publicly so readers can submit fixes via pull requests.
  • Keep Docs Current: Automate as much as possible. Generate reference docs from your API spec or code, and deploy updates alongside code releases. Outdated documentation frustrates developers, so strive to keep it “live and in sync” with your API.

By following these guidelines and learning from examples like Stripe, Twilio, and GitHub, technical writers and API product managers can create documentation that truly empowers developers. The goal is documentation that acts both as a reference manual and a guided tutorial — thorough, example-rich, and easy to navigate. Such high-quality docs will speed integration, reduce support load, and build a stronger developer community around your API.