Build an API Contract That Can Fail Clearly

In this chapter

• Distinguish invalid client input from downstream failure.
• Test accepted and rejected payloads.
• Avoid turning a model's output into an unrestricted API call.

Treat the contract as a boundary

An assistant's output is another input to your system. A model may produce an extra property, omit a required field or propose a category the service does not support. The API boundary must validate the final request independently of the prompt and browser form. For Relay Room, start with a versioned draft object containing room, summary and category. Reject unsupported keys so a future integration cannot accidentally accept an owner, approval flag or ticket status supplied by a caller.

Separate failure types. A client can correct a malformed draft, so return a stable error identifying the field. An unavailable ticket provider is different: retain the approved draft and report a retryable delivery state. Do not disguise both as an empty success object. A real HTTP adapter maps these cases to distinct status codes; this lab keeps the contract as a pure function so tests remain independent of networking.

Test the behavior before the transport

This worked example deliberately omits authentication and persistence, which belong to other boundaries. Its useful property is that success and failure have explicit shapes. The tests use an exact type check to avoid treating a number as a valid room name. Run the file directly: it should report two passing tests.

import unittest

def validate_draft(body):
    fields = {"room", "summary", "category"}
    if not isinstance(body, dict) or set(body) != fields:
        return {"ok": False, "error": "invalid_fields"}
    for key in ("room", "summary"):
        if type(body[key]) is not str or not body[key].strip():
            return {"ok": False, "error": "invalid_" + key}
    if body["category"] not in ("furniture", "cleaning", "presentation-equipment"):
        return {"ok": False, "error": "invalid_category"}
    return {"ok": True, "draft": {key: body[key].strip() for key in fields}}

class ContractTests(unittest.TestCase):
    def test_valid(self):
        self.assertTrue(validate_draft({"room": "Cedar 204", "summary": "Need cable", "category": "presentation-equipment"})["ok"])
    def test_extra_authority_is_rejected(self):
        self.assertEqual(validate_draft({"room": "Cedar 204", "summary": "Need cable", "category": "presentation-equipment", "approved": True})["error"], "invalid_fields")

if __name__ == "__main__":
    unittest.main()

Plan retries before users double-click

A common failure appears after validation succeeds: the browser times out, retries and creates two tickets. A transport timeout does not prove that the remote action failed. Define a stable operation identifier before sending a side effect. The ticket adapter must either support idempotency for that identifier or provide a lookup that permits reconciliation. An in-memory dictionary can demonstrate this behavior, but cannot survive a process restart or coordinate multiple replicas.

Document field limits, version compatibility and error semantics beside the fixtures. Avoid logging the entire request as a shortcut for troubleshooting; summaries can contain names or sensitive workplace details. Log a correlation identifier, validation category and timing instead. Contract tests should establish what consumers may rely on without making them depend on internal implementation details or unpredictable generated text.

Expand the rejected-input matrix

• Add tests for a numeric room, an empty summary, an unknown category and a missing property.
• Specify a maximum summary length and implement it without silently truncating the user's words.
• Write a brief retry contract explaining what happens if ticket creation succeeds but its response is lost.

Expected checks

• Every malformed fixture returns ok false and a stable error code.
• Extra authority fields never appear in accepted drafts.
• The retry design identifies a durable operation key and a reconciliation strategy.

Check your understanding

A request times out after reaching the ticket provider. What may the caller conclude?

• No ticket was created.
• A ticket was definitely created.
• The outcome is unknown until the same operation key is reconciled or safely retried.

Official tools & further reading

• Python unittest reference