API design

These guides connect evidence vocabulary, stable error reasons, and contract tests. Read them together before choosing which field the client will treat as a completion signal. A successful request, a passed observation, and permission to continue are different pieces of the contract.

During review, write the meaning of each state in one sentence. Add a fictional example and an expected next action. Keep unknown and unperformed checks visible, and make sure a future status does not silently become success in an older client.

Each guide includes a primary reference and links to related documentation. Use the articles as a review starting point, then align the recommendations with the actual methods, data, and policies of your implementation.