Exercise: API Documentation Reading Lab

Build the mental model

Reading documentation quickly and accurately is the real bottleneck when you integrate with an unfamiliar API — not writing the request code, which is usually trivial once you know what to send. The Advanced chapter walked through a method for approaching a real docs page section by section.

This exercise gives you a compact, self-contained sample to apply that method to immediately. Below is an excerpt from a fictional "Bookshelf API" — a made-up service for a book review app, written the way a real provider would write it.

Base URL — the root address every request builds on
Authentication method — how the request proves who is calling
Endpoint path and HTTP method — exactly what to call and how
Required vs. optional parameters — path, query, and their defaults
Required headers — what must be attached to every call
Request body shape — or confirmation that none is needed
Response shape — the fields you can expect back
Error codes and rate limits — what can go wrong, and how often you can call it

A reusable habit

Treat this as a checklist you run against any new API before writing a single line of integration code, not just as a one-off exercise for this lesson.

The habit of methodically locating each of these nine things, in order, is what separates a smooth integration from hours of guessing and trial-and-error against a live service.

text

ANATOMY OF AN API DOC
---------------------
BOOKSHELF API DOCUMENTATION - LABELED PARTS
---------------------------------------------
[BASE URL]   https://api.bookshelf-demo.dev/v1
[AUTH]       Bearer Token via Authorization header

[ENDPOINT]   GET /books/{bookId}/reviews
[METHOD]     GET
[PARAMS]     path:  bookId (required)
             query: page (default 1)
                    limit (default 20, max 100)
[HEADERS]    Authorization: Bearer <token>  (required)
             Accept: application/json       (optional)
[BODY]       none (this is a GET request)
[RESPONSE]   { data: [ {id, rating, comment} ],
               meta: { page, totalPages } }
[ERRORS]     401 invalid token, 404 not found, 429 rate limit
[RATE LIMIT] 100 requests per minute per token

Connect it to a real scenario

Here is how an experienced developer works through the Bookshelf API excerpt, so you can check your own answers after attempting the exercise yourself.

Base URL and auth

The base URL is the fixed prefix every path gets appended to. The auth line says Bearer Token, meaning every request needs an Authorization: Bearer <token> header, not a query-string API key.

Endpoint, method, and parameters

Isolate GET /books/{bookId}/reviews. The curly braces mark bookId as a required path parameter. The query parameters page and limit are optional because the doc lists defaults.

Headers and body

Authorization is required and Accept is optional. There is no request body, which is expected for a GET request.

Response, errors, and limits

The response has a data array plus a meta object for pagination. The error codes (401, 404, 429) and the rate limit tell you what your calling code must handle.

The code sample below turns this exact reading process into a small, reusable script that prints a clean call summary from a documentation-shaped object.

The nine things to extract from any API doc: base URL, auth, endpoint/method, params, headers, body, response shape, errors, and rate limit.
Curly braces in a path (like {bookId}) mark a required path parameter you must substitute with a real value.
A parameter listed with a default value is optional — you only send it to override that default.

Try the working example

javascript

const bookshelfApiDocs = {
  baseUrl: "https://api.bookshelf-demo.dev/v1",
  auth: {
    type: "Bearer Token",
    header: "Authorization: Bearer <token>"
  },
  endpoint: {
    method: "GET",
    path: "/books/{bookId}/reviews",
    description: "Returns a paginated list of reviews for one book.",
    pathParams: [
      { name: "bookId", type: "string", required: true, description: "The book's unique ID." }
    ],
    queryParams: [
      { name: "page", type: "integer", required: false, default: 1, description: "Page number." },
      { name: "limit", type: "integer", required: false, default: 20, description: "Max 100 per page." }
    ],
    headers: [
      { name: "Authorization", required: true, description: "Bearer <token>" },
      { name: "Accept", required: false, description: "application/json" }
    ],
    requestBody: null,
    responseShape: {
      data: [{ id: "string", rating: "number", comment: "string" }],
      meta: { page: "integer", totalPages: "integer" }
    },
    errors: [
      { status: 401, meaning: "Missing or invalid bearer token" },
      { status: 404, meaning: "Book not found" },
      { status: 429, meaning: "Rate limit exceeded" }
    ],
    rateLimit: "100 requests per minute per token"
  }
};

function summarizeEndpoint(doc) {
  const e = doc.endpoint;
  const lines = [];
  lines.push(`Base URL: ${doc.baseUrl}`);
  lines.push(`Auth: ${doc.auth.type} -> ${doc.auth.header}`);
  lines.push(`Call: ${e.method} ${doc.baseUrl}${e.path}`);

  const requiredPath = e.pathParams.filter(p => p.required).map(p => p.name);
  if (requiredPath.length) {
    lines.push(`Required path params: ${requiredPath.join(", ")}`);
  }

  const optionalQuery = e.queryParams
    .filter(p => !p.required)
    .map(p => `${p.name} (default ${p.default})`);
  if (optionalQuery.length) {
    lines.push(`Optional query params: ${optionalQuery.join(", ")}`);
  }

  const requiredHeaders = e.headers.filter(h => h.required).map(h => h.name);
  lines.push(`Required headers: ${requiredHeaders.join(", ")}`);
  lines.push(`Request body: ${e.requestBody ? "yes" : "none"}`);
  lines.push(`Possible error codes: ${e.errors.map(err => err.status).join(", ")}`);
  lines.push(`Rate limit: ${e.rateLimit}`);
  return lines.join("\n");
}

console.log(summarizeEndpoint(bookshelfApiDocs));

You should see

Base URL: https://api.bookshelf-demo.dev/v1
Auth: Bearer Token -> Authorization: Bearer <token>
Call: GET https://api.bookshelf-demo.dev/v1/books/{bookId}/reviews
Required path params: bookId
Optional query params: page (default 1), limit (default 20)
Required headers: Authorization
Request body: none
Possible error codes: 401, 404, 429
Rate limit: 100 requests per minute per token

5-minute try-it

Before reading the walkthrough in the practical section, work through the sample "Bookshelf API" documentation yourself and write down: (1) the base URL, (2) the authentication method and exactly how it's sent, (3) the endpoint's path and HTTP method, (4) which parameters are required vs. optional and their defaults, (5) which headers are required, (6) whether there is a request body, (7) the shape of a successful response, (8) every error code the doc mentions and what triggers it, and (9) the stated rate limit. Then check each answer against the walkthrough below.

One important caution

Assuming an optional parameter is unnecessary rather than reading why it exists — some optional params change behavior significantly (like limit affecting response size and rate-limit consumption).

Skipping the error codes and rate limit sections because they don't seem relevant until the integration is already live and failing in production.

Stripe API Reference (real-world example of a well-documented API) — API Integration & Webhooks