APIs & contracts
An API is a doorway with rules. You knock with a request; you get a response. The contract is the agreement about what that knock and reply look like — so neither side has to guess.
Think post office, not magic
Address (URL), method (what kind of action), envelope (headers / auth), letter (body). The other system promises a shape of reply, including how it tells you something went wrong.
What you should be able to explain
- What goes in and what comes out (fields and types — see data types).
- Who is allowed to call it (keys, users, roles).
- What “failure” looks like — and whether you can safely retry.
- Whether the other side might change the contract later.
Why this beats a clever prompt
Prompts are great for drafting. Contracts are what keep production from falling over when someone renames a field on a Tuesday. Ask your AI to draft against a contract, not against vibes alone — then keep the contract where humans can read it.