Writing API Endpoint Reference Docs
Practice writing clear API endpoint documentation: HTTP method, path, parameters, request/response examples.
API endpoint reference structure
- Endpoint line: HTTP method + path —
GET /users/{"{userId}"} - Description: 1–3 sentences — what it does, constraints, side effects
- Parameters: name, type, required/optional, default, description
- Request body: schema with field types, constraints, and enum values
- Responses: each status code + label + trigger condition + body shape
Question 0 of 5
Which sentence correctly distinguishes a path parameter from a query parameter in endpoint documentation?
Path parameters identify the resource; query parameters filter or modify the response. Standard API documentation convention:
- Path parameter: part of the URL path, surrounded by curly braces —
GET /users/{userId}. Required to address a specific resource. - Query parameter: appended after
?—GET /users?role=admin&limit=20. Usually optional and used for filtering, sorting, or pagination.
Which phrasing correctly documents a parameter as required vs. optional?
Professional API documentation uses parenthetical labels with a default value for optional parameters. The pattern is:
paramName (required|optional, default: X) — description in sentence form.- The label (required) or (optional) makes it machine-scannable and human-readable.
- Documenting the default value for optional parameters tells consumers what happens when they omit it — critical for predictable integration.
- The description is a full sentence or noun phrase, not a repeat of the name.
Which sentence best documents a response status code in an API reference?
Status code documentation must name the code, its standard label, the exact condition that triggers it, and what is in the response body.
201 Created— always pair the numeric code with the HTTP standard reason phrase.- "when the resource has been successfully created" — state the exact trigger condition, not just "if it works".
- "The response body contains..." — tell the consumer what they will receive, so they know what to parse.
400 Bad Request if the email field is missing or malformed." This lets developers write precise error-handling logic.Which excerpt best describes a request body schema for a POST endpoint?
Request body documentation must list every field with its type, required/optional status, constraints, and allowed values. The pattern for each field:
fieldName type, required|optional, default if applicable — description with constraints and valid values.- Type —
string,integer,boolean,arrayetc. - Constraints — min/max length, format (e.g. RFC 5321 for email), regex pattern.
- Enum values — list all allowed values for string enums.
What should an endpoint description include, and approximately how long should it be?
An endpoint description answers: what does this endpoint do, in 1–3 sentences, with any non-obvious constraints or side effects.
- What it does — active-voice verb phrase: "Creates a new user account and sends a verification email."
- Key constraints — rate limits, authentication requirements, idempotency: "This endpoint is idempotent — calling it twice with the same key has no additional effect."
- Side effects — triggers, webhooks, emails: "Triggers a
user.createdwebhook event."