You already use interfaces in hardware: an initiator supplies a request, a target returns a response, and both follow a contract. An API is a software interface with a similar need for a defined contract. It is not an AXI transaction: transport, timing, retries and error meanings are different. For this course, start with a request for a synthetic regression summary, not a model-provider SDK.
Illustrative exchange, not a real service call
GET /runs/run-014
request: retrieve one approved run record
response status: 200
response body: {"run_id":"run-014","test":"fifo_wrap","status":"FAIL","revision":"r3"}
next action: validate the body, then include the record as evidenceConcept | What it means | What to check |
|---|---|---|
Endpoint and method | Where the request goes and which operation it asks for. | Use an approved endpoint and supported method; a read-looking name is not proof of no side effects. |
Arguments and body | The run ID, query or other structured input. | Validate allowed values and minimise the data sent. |
Authentication | Evidence of the caller's identity. | Use the application's approved credential mechanism; never paste credentials into a prompt or lesson output. |
Authorisation | Which operation and data that caller may access. | Authentication does not grant access to every project. |
Response | Status plus returned data. | A successful transport response does not establish that an AI explanation is correct. |
An HTTP 401 indicates missing or invalid authentication; a 403 means the request is forbidden. Do not ask the assistant to bypass either. A 429 indicates a rate limit; follow the service's retry guidance and the run budget. A timeout leaves the outcome uncertain, particularly for a job submission: retrying can launch a second job. Use approved deduplication or ask the owner to reconcile state. A finite step budget alone cannot stop one tool call that hangs forever; the actual executor also needs request and job timeouts.
Your log assistant receives 200 with the wrong run_id, 403 for another project's report, and a timeout after submitting a simulation. For each, decide whether to accept, retry or escalate, and name the evidence you need.
Reject the mismatched record and investigate request/response correlation. Respect the 403 and ask for approved access if necessary. Reconcile the simulation's status before any retry; a timeout does not prove it was never started.
Optional reading: HTTP semantics defines status codes and method semantics. Model APIs add their own schemas, limits and billing. Consult the chosen service's current documentation rather than transferring the synthetic response shape to it.