This task is one section of Eight software practices that keep business apps reliable, with 7 related tasks on one page.
1. Describe one operation
Write the method, the path, who may call it, and the fields. Mark which fields are required.
2. List the failures
Say what a missing field, a forbidden caller, and a missing record look like. A client cannot handle an error you have not named.
3. Give one example each
Include one successful body and one failed body. Keep real customer data out of the examples.
4. Version a breaking change
Adding an optional field is usually safe. Removing or renaming a field needs a new path or a version, and a date when the old one stops.
5. Frequently asked questions
Is a conversation enough?
No. Write it down where the caller can read it without asking you.
Do I document every future idea?
Document the operation you are ready to keep. Mark the rest as not available.
What if the implementation disagrees with the contract?
Fix one of them before a second team binds to the wrong behavior.
6. Related articles and next steps
Treat the checks below as the acceptance test for the change. Names of libraries can vary; the behavior to prove does not.