A Checklist for a New Endpoint

Every endpoint in this book was built by answering the same questions. Here they are in the order you meet them.

Shape

• Is it a resourceful action (index, store, show, update, destroy) on a plural noun? If not, is there a good reason?
• Does the controller method only receive a request and return a response?
• Is the status code true? 201 for created, 202 for accepted and queued, 204 for done with nothing to return.

Input

• Is every field validated in a FormRequest, including query parameters?
• Does every string, array, and number have an upper bound?
• Is the model given validated(), never all()?

Output

• Does the response go through a Resource, with data as the envelope?
• Is every field in the Resource meant to leave?
• Can the Resource run a query? It shouldn’t be able to.

Authorization

• Which ability does the token need, and is that declared on the controller?
• If the endpoint takes an ID, which records may this caller touch, and where is that rule?
• Is there a test in which the wrong caller asks?

Failure

• What does the consumer see when the provider is down?
• If a consumer retries this request, what happens the second time?
• Does anything it queues survive running twice?

Operations

• Does a list paginate, with a capped page size?
• Is any new query covered by an index?
• Is the work logged with the trace ID, and without secrets?
• Does it appear in the generated documentation, with a sentence saying what it is for?
• Is there a changelog entry?

An endpoint that answers all of these is finished. One that can’t answer them is a prototype, however well it demos.