HTTP API requests and interpretable responses

An HTTP API request combines a method, target, headers and optional content, while the response status and operation contract define its result.

An HTTP request identifies an operation through its method and target. Headers supply additional context, including authentication and content type. Some operations also receive a body.

The response contains a status and, when applicable, content describing the result. A successful network connection is only the beginning of that exchange.

A request has independently meaningful parts

This original HTTP/1.1 fragment illustrates a library query with fictional identifiers:

GET /emby/Users/example-user/Items?StartIndex=0&Limit=2 HTTP/1.1
Host: media.example.invalid
X-Emby-Token: EXAMPLE_TOKEN
Accept: application/json

It would be carried over an appropriately authenticated HTTPS connection in the described arrangement. No request is sent by this example.

Part Meaning
GET Requests a representation under HTTP semantics
Target path Identifies the documented server resource
Query parameters Supply inputs for this operation
X-Emby-Token Emby's documented request credential header
Accept States a preferred response media type

A GET normally retrieves information rather than requesting a state change. The actual endpoint still defines its parameters and returned representation.

The response needs its operation context

A 200 response indicates successful handling with the applicable representation. A 202 response means acceptance for processing; it does not assert that all later work is complete. A 401 or 403 points to authentication or refusal under HTTP semantics, but the server's documented behavior supplies the detailed diagnosis.

Malformed input, a missing resource and a failed server operation are other outcomes. Parsing JSON successfully is not enough if the response describes an error rather than the expected result.

The exact status, relevant headers and body belong together.

Response loss creates uncertainty

Suppose a state-changing request reaches the server and completes, but the connection closes before the client receives its response. From the client's observation, the outcome can be unknown.

Repeating an idempotent operation preserves the intended effect under its contract. Repeating another operation, such as adding another object, can instead duplicate work. A POST method alone does not supply a universal safe-retry rule.

Use the documented operation identity, idempotency support or a suitable state query to resolve that uncertainty. Event delivery and retries develops the same distinction between delivery evidence and completed effects.

See Also

References