Design an API endpoint from a vague request: route, data, and errors

Where to start

Before you think about a controller or handler, answer a few simple questions:

• Is this a read operation or a state change?
• Which resource are we creating, reading, or updating?
• Who will call the endpoint: browser, mobile app, backend service, or an external client?
• Which fields are required, and which are optional?
• What should happen if input is incomplete, invalid, or conflicting?

If you do not have those answers yet, do not rush into code. First decide the shape of the endpoint.

Turning the feature request into an endpoint

A good endpoint does not appear out of thin air. It is built from several decisions:

• the route shows which resource you are touching;
• the HTTP method shows the intent;
• the request contract describes the input;
• the response contract describes the result;
• validation defines what is acceptable;
• the status code shows how the request ended;
• the auth boundary defines who may do it at all.

That order removes the magic. Instead of “let’s make an endpoint,” you get a set of concrete decisions.

What to fix before coding

1. Route and resource

Start by naming the resource in plain language. For example, not “request helper” but “order”, “profile”, “invoice”, or “comment”.

Then attach the method:

• GET for reading;
• POST for creating;
• PATCH for partial updates;
• DELETE for removing;
• PUT for a full replacement, if that is truly needed.

2. Request contract

Next, fix what comes in:

• which fields are required;
• which fields are optional;
• which types and formats are expected;
• what to do with empty strings, nulls, and unknown fields.

3. Response contract

You also need to know what comes back:

• only an acknowledgment;
• the created resource;
• the updated resource;
• a dedicated error structure;
• a minimal payload for the client.

4. Validation and errors

Beginners often think about validation after implementation, but this is where the endpoint becomes predictable or not.

• 4xx means the client request has a problem.
• 5xx means the issue is on the server side or in a dependency.
• If a rule can be checked before business logic runs, check it early.

5. Auth boundaries

When an endpoint touches user data or a sensitive action, decide separately:

• whether authentication is required;
• whether authorization is required;
• whether there is a role-level or resource-level check;
• whether the endpoint opens more access “for convenience.”

6. First tests

Before coding, you should already know the first tests:

• happy path;
• a negative case with invalid data shape;
• a case with denied access;
• a case with a missing or empty required field.

These tests make the design visible. If they are hard to name, the endpoint is not fully designed yet.

What not to decide yet

Do not try to solve every detail immediately:

• do not choose a complicated response format if a simple one is enough;
• do not expand auth “for the future”;
• do not mix multiple business actions into one endpoint;
• do not push ambiguity into code when it should be discussed first.

Good endpoint design often looks boring. That is a good sign: a boring contract is easier to test, document, and maintain.

Prompt template

Copy this prompt and paste it together with a short feature description, the fields you already know, and any limits or open questions:

You are helping design an API endpoint for a real feature request.

Context:
- Feature request: [paste a short description]
- Who calls the endpoint: [browser / mobile app / backend service / external client]
- Action: [read / create / update / delete / other]
- Input data: [paste the known fields]
- Expected result: [paste the response fields]
- Known edge cases: [paste a list or write "none yet"]
- Access: [required / not required / unclear]

Tasks:
1. Turn the request into a concrete endpoint plan: route, method, and resource.
2. Describe the request contract and response contract.
3. Separate validation rules, errors, and status codes.
4. Point out where authentication or authorization boundaries are needed.
5. Suggest the first 2-3 tests to write before implementation.
6. If there are several design options, briefly compare them and choose one.

Output format:
- Endpoint summary
- Request contract
- Response contract
- Validation and errors
- Access boundaries
- First tests
- Open questions

Bottom line

A good API endpoint starts with a clear contract, not with code. If the feature request is still fuzzy, this template helps turn it into a route, method, fields, errors, access rules, and tests.