The Backend Playbook

Appearance

Controllers ​

Are your gateway to the world wide web. We use decorators to describe the endpoints and their behavior.

Controller decorator ​

Controllers are responsible for handling incoming requests and returning responses to the client. Controllers should be decorated with the @Controller decorator and registered in the module under the controllers property to expose the routes to the application. For a more detailed explanation, check out the NestJS documentation.

Path ​

  • Use Nouns to represent resources / Not Verbs
    • ✅: /employees/{employeeUuid}
    • ❌: /getEmployees/{employeeUuid}
  • Use Pluralized Nouns for resources
    • ✅: /items/{itemUuid}, /employees/{employeeUuid}/address
    • ❌: /item/{itemUuid}, /employee/{employeeUuid}/address
  • Use hyphens (-) between words
    • ✅: /vendor-management/{vendorId}, /inventory-management
    • ❌: /vendormanagement/{vendorId}, /inventory_management
  • Use forward slashes (/) for hierarchy but not trailing forward slash (/)
    • ✅: /items
    • ❌: /items/
  • Version your APIs for backwards compatibility
    • ✅: /v1/employees/{employeeUuid}, /v2/employees/{employeeUuid}

Methods ​

Depending on its purpose, an endpoint will have a certain HTTP Request method. We listed the methods we use and when.

GET ​

Fetch one or multiple objects, no changes are made to the data. A successful GET requests return a 200 status code.

Use the @Get decorator to define a GET endpoint.

POST ​

Create a new object. Successful POST requests return a 201 status code.

Use the @Post decorator to define a POST endpoint.

PUT ​

Update an object by completely replacing it with new data. Successful PUT requests return a 200 status code.

Use the @Put decorator to define a PUT endpoint.

PATCH ​

Update an object by partially replacing it with new data. Successful PATCH requests return a 200 status code.

Use the @Patch decorator to define a PATCH endpoint.

DELETE ​

Delete an object. Successful DELETE requests return a 204 status code.

Use the @Delete decorator to define a DELETE endpoint.

Documentation ​

NestJS provides a set of useful decorators to generate OpenAPI Swagger documentation for your endpoints. See the NestJS documentation for a more detailed overview.

Tags ​

To group endpoints in the Swagger documentation, you can use the @ApiTags decorator.

Responses ​

To document a successful response of an endpoint, you can use the following decorator, It accepts a status code and a class that will be used to generate the response schema from your response class

  • @ApiOkResponse({ status: statusCode, type: ResponseClass })

For common status codes, NestJS provides some shorthand decorators that inherit from the @ApiResponse decorator

  • @ApiOkResponse({ type: ResponseClass }) for status code 200
  • @ApiCreatedResponse({ type: ResponseClass }) for status code 201
  • @ApiNoContentResponse() for status code 204

Errors ​

To document possible errors that can occur when calling an endpoint, you can use the following decorator. It accepts a status code and a class that will be used to generate the response schema from your error class

  • @ApiErrorResponse(statusCode, ErrorClass)

For common status codes, we have created some shorthand decorators that inherit from the @ApiErrorResponse decorator

  • @ApiBadRequestErrorResponse(ErrorClass) for status code 400
  • @ApiConflictErrorResponse(ErrorClass) for status code 409

Permissions ​

For defining permissions required to use an endpoint, you can use the @Permissions decorator which accepts one or more permissions as arguments. Permissions are validated by the guards from the Auth module. They use the permissions from the roles resolved by the auth middleware.

For public endpoints, you use the @Public decorator.