Restful API

Presentation

REST (Representational State Transfer) is a standard to describe how to implement networked applications (consumed by other applications or a frontend for instance). It almost always relies on HTTP protocol.

Key benefits for this project:

• maintanability : separation of concerns between the frontend and backend

Installation

Documentation

OpenAPI heps to generate interactive documentation from decorators in the codebase (in controllers and DTOs).

Decorators

on controller class :

• @ApiTags to group endpoints under a category (i.e. "users")
• @ApiBearerAuth() if the endpoint requires authentication
• @Controller

on function

• method such as @Get(:param)
• @ApiOperation with attributes summary : description
• @ApiParam with attributes name, description
• @ApiQuery
• @ApiResponse (status, description, type: DTO) for each possible case

on DTO fields

• @ApiProperty (example, description, required)

Do's & Don'ts

✅ Do	❌ Don't
Use DTO for request bodies and response objects	Expose database entities
Use standard HTTP codes
Describe params
Document error cases	Ignore 4xx and 5xx

Note

RESTful API are stateless, so we should not store client context (such as 'current xxx', ...)

Resources

Type	Resource	Notes
📄	Official Specs 3.1.1	Main reference
📦	@fastify/swagger	to check
📦	@scalar/fastify-api-reference	to check
💻	Pro example	MS Azure guidelines - not checked
🎥	Documenter avec OpenAPI	php but transferable to project

Legend: 📄 Doc, 📘 Book, 🎥 Video, 💻 GitHub, 📦 Package, 💡 Blog