REST API design template

An endpoint table — method, path, auth, status codes — plus the conventions every endpoint follows.

Use this templateFree, opens in your browser. No sign-up.

REST API design template
Method
Path
Purpose
Auth
Success
Errors
GET
/v1/orders
List orders (cursor paginated)
user
200
401
POST
/v1/orders
Create an order
user
201
400, 409
GET
/v1/orders/:id
Get one order
owner
200
404
PATCH
/v1/orders/:id
Update shipping address
owner
200
400, 409
POST
/v1/orders/:id/cancel
Cancel if not shipped
owner
202
409
DELETE
/v1/orders/:id
Delete (admin only)
admin
204
403
Plural nouns, no verbs in paths (except actions like /cancel)
Version in the path: /v1
Errors: { code, message, details } with a stable code
Idempotency-Key header on POST
ISO 8601 dates, amounts in minor units
Conventions
API design
The REST API design template as it opens in Kelvo: 5 sticky notes and 1 table.

What's on the board

Table columns: Method, Path, Purpose, Auth, Success, Errors.

  • Conventions
  • Plural nouns, no verbs in paths (except actions like /cancel)
  • Version in the path: /v1
  • Errors: { code, message, details } with a stable code
  • Idempotency-Key header on POST
  • ISO 8601 dates, amounts in minor units

How to use this template

  1. Click Use this template. It opens in the Kelvo app as a new board, saved in your browser.
  2. Double-click any box to change its text. Replace the examples with your own content.
  3. Paste a table. Paste comma- or tab-separated text and it becomes a table. Tab moves to the next cell and adds rows as you go.
  4. Paste code as code. Paste a snippet and it becomes a code block with syntax colouring; Tab indents inside it.
  5. Link by dragging. Hover a box and drag one of its dots onto another box. The whole box is the target, and links stay attached when you move things.

Good for

  • api
  • rest
  • endpoints
  • backend
  • engineer
  • Designing a schema or an API before writing it
  • Explaining a tricky flow in a code review or design doc
  • Agreeing on team conventions such as branching and reviews

Related templates

  • Sequence diagram (request flow) template previewSequence diagram (request flow)

    Numbered steps across Client, API gateway, service, database and a third party — how one checkout request really travels.

  • ER diagram (database schema) template previewER diagram (database schema)

    Entities as tables with columns, types and keys, joined by one-to-many relationships — sketch a schema before the migration.

  • UML class diagram template previewUML class diagram

    Classes with fields and methods, associations with multiplicity, and an interface with two implementations.

  • State machine template previewState machine

    Every state an order can be in and the events that move it — the source of truth for status logic and tests.

  • Microservices with API gateway template previewMicroservices with API gateway

    Clients behind an API gateway, services that each own their database, and an event bus for asynchronous work.

  • Integration patterns compared template previewIntegration patterns compared

    Request/response, queues, pub/sub and batch transfer side by side, with coupling, latency and when to use each.

All software engineering diagram templates · All templates

Use the REST API design template