Read the contract behind a request

Identify the resource, method and representation

An HTTP request has a method, a target resource, headers and sometimes a body. A response has a status, headers and sometimes a representation. REST is an architectural approach; an endpoint calling itself REST does not remove the need to inspect its actual provider contract.

Our fictional resource is https://api.example.invalid/v1/assets. Its collection operation behaves like a GET: the client requests asset representations rather than changing asset ownership. The versioned path identifies the interface contract. A cursor query selects the next part of a collection. An Accept: application/json header would state a preference to a real provider; the received Content-Type still needs verification.

A target URI is not just a string to concatenate blindly. Scheme and origin determine where the request goes. The path identifies the resource. Query parameters influence selection. A fragment is normally a client-side identifier rather than a field the HTTP server receives in the request target. Our narrow client rejects fragments because they have no role in this page contract.

Do not put an access token in a query string for this project. Query strings can appear in logs, browser history and copied links. A real authentication adapter should use its provider's documented credential transport and avoid logging the credential. The offline fixture needs none.

Interpret status in context

A status in the success range does not guarantee the representation is the expected data. A particular endpoint may return 200 with a JSON object, 204 without a body, or another documented success outcome. Our collection contract requires exactly 200 with the expected JSON page. It does not try to parse an empty 204 as an inventory.

A 400 response often indicates a request-contract problem, such as an invalid query. A 401 response commonly concerns missing or unacceptable authentication, while 403 commonly indicates that the authenticated request is forbidden. Providers can expose more specific error codes and policies; read those before adding privileges or repeatedly refreshing a token. A 404 can mean a missing resource, a wrong path or an intentionally concealed resource. Status alone does not prove which explanation applies.

A 429 communicates rate limiting. A 503 communicates a service-unavailable condition. They may be eligible for a bounded retry under the endpoint's contract. Our example retries only those two statuses and a transport timeout. It stops for a forbidden request, invalid data or an unsupported redirect. Retrying a schema defect usually repeats the same problem; retrying permission failure can amplify noise without improving access.

Record the operation, safe correlation context, status and next diagnostic question. Do not log every response body automatically: it may contain confidential fields even when the request fails. This course's fictional data can be printed safely, but the habit should remain selective.

Authentication and authorization answer different questions

Authentication establishes the identity or credential accepted for a request. Authorization decides whether that identity can perform this operation on this resource. A token with a valid signature may still target a different API audience, lack the required scope, or represent an identity that has no access to the requested population.

In a human delegated flow, permissions can depend on both application consent and the signed-in user's authority. A workload flow has a different identity and permission model. The details are provider-specific. Before writing a collector, document the endpoint, operation, required permission, resource scope, identity owner and token-storage boundary.

“Use an administrator token” is not a dependable troubleshooting method. It can hide the actual missing permission and expand the collector's access far beyond the report. A read collector should use the narrow permission required for its resource, and changes to access require the environment's approved process. The lab avoids that dependency by using a transport that returns fixed in-memory responses.

Read the page schema manually

Our provider returns an object with exactly three properties:

{
  "items": [
    {"id":"A-002","owner_id":"u102","site":"HQ"},
    {"id":"A-001","owner_id":"u101","site":"HQ"}
  ],
  "next": "https://api.example.invalid/v1/assets?cursor=page2",
  "total": 3
}

items is an array of asset objects. next is either an approved absolute page URL or null. total is the number of distinct assets this collection claims to expose under the current query and access scope. It is an integer, not a numeric-looking string or a Boolean. The first page has two items even though the collection advertises three.

Each item has a stable case-sensitive id, an owner identity and an accepted site code. A valid item identifier has the form A-001. Exact field validation is intentionally strict in this first version. Accepting optional fields or schema evolution is a later project, with a documented compatibility policy.

Prediction exercise

The second page has one item, A-003,u103,BRANCH, a null next link and total 3. Predict the final sorted identifiers and number of transport calls. You should collect A-001, A-002, A-003 in that order with two successful page calls. The first page's display order does not become the export ordering contract.

Reason about a misleading first-page report

If the client returns the first page’s two items and ignores the next link, it has omitted A-003. A later reconciliation could wrongly call A-003 register-only. HTTP 200 on the first request establishes only a successful first-page response under this endpoint contract, not completed collection.

Reasoning model

Read and write retries have different consequences. A timed-out response does not prove the server did not perform the operation. For a create request, blindly retrying may duplicate a resource unless the API provides an applicable idempotency mechanism or a supported reconciliation path. Read the service contract for pagination, status handling and retry guidance. Keep credentials out of URLs, exception dumps and sample logs.

Official reference for further study