NestJS REST API

REST Conventions in NestJS

A RESTful API models data as resources, each with a predictable URL and a small set of HTTP methods that act on it. NestJS maps naturally onto this: a resource becomes a controller, and each REST operation becomes a decorated method.

@Controller('cats')
export class CatsController {
  @Get()        findAll() {}
  @Get(':id')   findOne() {}
  @Post()       create() {}
  @Put(':id')   replace() {}
  @Patch(':id') update() {}
  @Delete(':id') remove() {}
}

This single controller implements the full standard REST surface for the cats resource, list, read, create, replace, partial update, and delete.

REST Method-to-Operation Mapping

GET    /cats       -> list all cats
GET    /cats/:id   -> get one cat
POST   /cats       -> create a cat
PUT    /cats/:id   -> replace a cat entirely
PATCH  /cats/:id   -> update part of a cat
DELETE /cats/:id   -> delete a cat

• Resource collections use plural nouns in the URL, like /cats, not verbs like /getCats.
• The HTTP method, not the URL, conveys the action being performed.
• Nested resources express relationships, like /cats/:id/vaccinations.
• Status codes communicate the outcome: 200, 201, 204, 400, 404, and so on.

REST API Cheatsheet

Standard REST conventions applied inside a NestJS controller.

Designing Resource-Oriented Endpoints

Good REST design starts with identifying nouns (resources), not verbs. Instead of /createCat or /getCatById, model the resource as /cats and let the HTTP method express the action.

• Use plural nouns for collections: /cats, not /cat.
• Model relationships as nested resources: /cats/:id/vaccinations.
• Avoid verbs in URLs, the HTTP method already conveys the action.
• Keep the resource shape (the DTO/entity) consistent across list and detail endpoints.

Keeping Response Shapes Consistent

Consumers of your API benefit from consistent, predictable response shapes, the same fields for a single resource whether it's returned from a list endpoint or a detail endpoint, and a consistent error format across every failure case.

Common Mistakes

• Using verbs in URLs (/getCats, /createCat) instead of relying on HTTP methods.
• Returning 200 OK for every response regardless of the actual outcome.
• Inconsistent response shapes between list and detail endpoints for the same resource.
• Not versioning the API before making a breaking change to a resource's shape.

Key Takeaways

• REST APIs model data as resources with predictable, noun-based URLs.
• HTTP methods (GET, POST, PUT, PATCH, DELETE) express the action, not the URL.
• Status codes should accurately reflect the outcome of each operation.
• Nested resources express relationships between related entities.