Jason Bariamis

Documentation guide

Write a clear API endpoint description

A practical guide for turning API behavior into clear, useful endpoint descriptions for developer documentation.

Back to guides

Before you write

Before writing the endpoint description, confirm the endpoint purpose, required identifiers, permissions, request body, response fields, and common failure cases. Do not guess missing behavior.

Procedure

Steps

  1. 1

    Start with what the endpoint does

    Describe the user-facing purpose of the endpoint before explaining technical details. A developer should understand when and why to use the endpoint after reading the first sentence.

  2. 2

    Name the resource clearly

    Identify the object or resource the endpoint works with, such as submittal items, tasks, attachments, users, issues, or cost items.

  3. 3

    Explain the action

    Use a precise verb that matches the endpoint behavior. For example: create, retrieve, update, delete, validate, transition, close, copy, or link.

  4. 4

    Mention important conditions

    Include required context, permissions, workflow state, or dependencies that affect whether the request succeeds.

  5. 5

    Avoid backend implementation detail

    Do not describe internal services, database behavior, or implementation logic unless the reader needs that information to use the API correctly.

  6. 6

    Connect the response to the task

    Explain what the response gives the developer and how it helps them continue the workflow.

Example

Weak

This API is used to get data from the system.

Better

Retrieves the submittal item details for the specified project and item ID, including status, assignee, due date, and related metadata.

Writing note

A strong endpoint description explains the task, the resource, the action, and the result. It helps developers decide whether the endpoint is the right tool before they inspect the request and response details.