HTTP as a contract
Design requests and responses that tell clients exactly what happened.
BY THE END, YOU CAN
- Identify methods, paths, headers, and bodies
- Distinguish acceptance from completion
- Define retry behavior for an asynchronous API
Diagram description: 1. Client → API: POST /jobs {payload}; 2. API → Client: 202 Accepted · id=42; 3. API → Worker: job 42 queued; 4. Client → API: GET /jobs/42; 5. API → Client: 200 {"status": "running"}
A request asks for an operation
HTTP carries a method, a target, headers, and sometimes a body.
The method contributes semantics: GET retrieves a representation, while POST commonly submits data for processing. A response includes a status code, headers, and optional content. Design these together rather than treating the API as a remote function with arbitrary strings.
For Relay, POST /jobs accepts a job and GET /jobs/{id} retrieves its status. Validate content type and payload shape before creating work, and return an identifier clients can use later.
Accepted is not completed
A queue API often acknowledges that work was accepted before the work is finished.
A 202 response can express that distinction, while its body or a link tells the client how to inspect progress. Specify whether acceptance means durable storage or merely memory; these promises differ during a crash. A timeout is ambiguous: the server may have accepted the job even though the client received no response.
That ambiguity is why a retryable create operation often needs an explicit idempotency key.
Make errors useful and stable
Use status codes consistently and include a structured error code plus a safe, actionable message.
Separate malformed input, lack of authorization, missing resources, conflicts, and temporary overload. Do not leak internal traces or credentials in responses. Define limits on body size and request frequency so a single client cannot exhaust the service.
A client should know whether to correct its input, authenticate, wait, or stop retrying. Contract tests can verify these behaviors without depending on the framework's internal routing implementation.
COMMON FAILURE MODE
Returning success before the promised durability point creates a silent contract violation if the process crashes immediately afterward.
TRY IT YOURSELF
Specify request and response examples for creating a job and retrieving its status. Explain what a client should do after a timeout on creation.
Make the call in the laboratory.
The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.
Open in the laboratory ↗CONNECT IT TO RELAY
Write Relay's HTTP contract, including accepted-job responses, validation errors, polling, and the precise durability promise.