THE ENGINEERING NOTEBOOK
Start with the API boundary
A design checklist for turning a business action into a clear request and response.
Name the action
Before choosing a route, describe the user’s action in one sentence. Separate what the caller may provide from what the server must decide. This makes validation and ownership easier to discuss.
Make failure part of the contract
Consider missing data, invalid values, missing permissions, and unavailable dependencies. Give each situation a predictable response shape. Avoid exposing internal exception details to the caller.
Test the boundary
Start with a successful request and one meaningful failure. Add cases for ownership and repeated submissions when those matter to the workflow. The portfolio playground lets you compare successful, invalid, and missing-resource responses using sample data.