SSA Health Platform REST API Conventions and Patterns

The SSA Health Platform API is designed to be RESTful, predictable, and immediately approachable for any developer joining the project. Every endpoint follows the same structural rules — consistent URL shapes, uniform error envelopes, and standardized pagination — so that learning one part of the API transfers directly to every other part. All endpoints are automatically documented via NestJS Swagger decorators and exposed through an interactive UI, meaning the contract between the backend and any consumer (the React admin panel, the public website, or third-party integrations) is always machine-readable and up to date.

Base URL

All API requests are made relative to the environment base URL:

Development: http://localhost:3000
Production:  https://api.ssa.gob.mx

The interactive Swagger UI is available at:

{BASE_URL}/api/docs

In production environments, the Swagger UI should be disabled or protected behind HTTP Basic Auth to prevent public exposure of your API surface.

Authentication

The SSA Platform uses JSON Web Tokens (JWT) for stateless authentication. Every protected endpoint requires a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Obtain a token by posting credentials to the login endpoint:

POST /auth/login
Content-Type: application/json

{
  "email": "admin@ssa.gob.mx",
  "password": "your-password"
}

The response includes a short-lived access token (default 15m) in the JSON body. A longer-lived refresh token (default 7d) is issued automatically as an HttpOnly cookie — it is never accessible to JavaScript and is sent back to the server automatically on refresh requests. To obtain a new access token without re-authenticating, call:

POST /auth/refresh

Access tokens expire quickly by design. Build your API client to detect 401 Unauthorized responses and silently call /auth/refresh before retrying the original request.

URL Conventions

URL design follows strict REST principles: routes identify resources, never actions. The HTTP verb alone communicates the operation. Rules:

Use nouns, never verbs: /content not /getContent
Use plural resource names: /content, /multimedia, /timeline
Use nested routes for child resources: /content/:id/media
Use query parameters for filtering, sorting, and pagination
No trailing slashes

Examples:

✅ GET    /content?type=news&status=published&page=1&limit=20
✅ POST   /content
✅ GET    /content/uuid-here
✅ PUT    /content/uuid-here
✅ DELETE /content/uuid-here

❌ GET    /getContent
❌ POST   /createContent
❌ GET    /content/

All resource identifiers use UUID v4, never sequential integers, to prevent enumeration attacks and to support eventual distribution across services.

Pagination

All list endpoints use offset-based pagination. The page and limit query parameters are supported universally:

GET /content?page=2&limit=20

Every list response wraps its payload in a consistent envelope:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 2,
    "limit": 20,
    "totalPages": 8
  }
}

Never request list endpoints without a limit parameter. The API enforces a maximum of 100 items per request. Requests without a limit will use the default value defined in the module (typically 20), and requests that exceed 100 will be clamped automatically.

HTTP Status Codes

The API uses standard HTTP status codes consistently. Never infer success from the response body alone — always check the status code first.

Code	Meaning
`200`	OK — successful `GET` or `PUT`
`201`	Created — successful `POST`
`204`	No Content — successful `DELETE`
`400`	Bad Request — DTO validation error
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — authenticated but insufficient permissions
`404`	Not Found — resource does not exist
`409`	Conflict — duplicate slug or unique constraint violation
`422`	Unprocessable Entity — business rule violation
`500`	Internal Server Error — unexpected failure

Error Response Format

All error responses return a consistent JSON envelope regardless of the error source. Clients should always parse this shape to surface meaningful messages to users:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "title",
      "message": "title should not be empty"
    }
  ],
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/content"
}

The errors array is populated on 400 validation failures and contains one entry per failing field. For non-validation errors (401, 403, 404, 409, 500), the errors array is omitted and message contains a human-readable explanation.

DTO Validation

All incoming payloads are validated using class-validator decorators on Data Transfer Objects (DTOs) before execution reaches the service layer. Controllers never touch raw request data directly — they only receive typed, validated DTO instances.

src/modules/cms/dto/create-content.dto.ts

export class CreateContentDto {
  @IsNotEmpty()
  @IsString()
  @MaxLength(255)
  title: string;

  @IsEnum(ContentType)
  type: ContentType;

  @IsOptional()
  @IsString()
  slug?: string;

  @IsOptional()
  body?: Record<string, unknown>; // Tiptap JSON

  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  tags?: string[];

  @IsOptional()
  @IsArray()
  @IsUUID('4', { each: true })
  mediaIds?: string[];
}

A global ValidationPipe with whitelist: true and forbidNonWhitelisted: true is registered at application bootstrap. This strips any properties not declared on the DTO and throws a 400 if unknown properties are present, protecting the service layer from unexpected input.

Use @IsOptional() together with the relevant validator decorator (e.g. @IsString()) when a field is not required. @IsOptional() alone does not validate the type if the field is present.

Swagger Documentation

Every controller and endpoint is annotated with NestJS Swagger decorators so that the /api/docs UI always reflects the live API contract with no manual maintenance required.

@ApiTags('Content')
@ApiOperation({ summary: 'Create new content item' })
@ApiResponse({ status: 201, type: ContentResponseDto })
@ApiBearerAuth()
@Post()
create(@Body() dto: CreateContentDto) { ... }

Key decorator conventions used across the project:

Decorator	Purpose
`@ApiTags('Module')`	Groups endpoints under a named section in the UI
`@ApiOperation({ summary })`	Short description visible in the endpoint list
`@ApiResponse({ status, type })`	Documents expected response shape per status code
`@ApiBearerAuth()`	Marks the endpoint as requiring JWT auth
`@ApiQuery({ name, required, enum })`	Documents query parameters
`@ApiParam({ name, type })`	Documents path parameters

Response DTOs decorated with @ApiProperty() are reflected automatically, giving consumers a full schema for every request and response object directly in the browser.

Tech Stack

Library choices, versions, and rationale for the full platform stack.

Coding Conventions

Naming rules, file structure, TypeScript standards, and Git commit format.

Testing Strategy

Unit and integration testing patterns for services, controllers, and DTOs.

Deployment

Environment configuration, database setup, and production checklist.

Stack & Setup

API & Deployment

SSA Health Platform REST API Conventions and Patterns

Base URL

Authentication

URL Conventions

HTTP Status Codes

Error Response Format

DTO Validation

Swagger Documentation

Tech Stack

Coding Conventions

Testing Strategy

Deployment

Build docs developers (and LLMs) love

Stack & Setup

API & Deployment

Documentation Index

​Base URL

​Authentication

​URL Conventions

​Pagination

​HTTP Status Codes

​Error Response Format

​DTO Validation

​Swagger Documentation

​Related Pages

Tech Stack

Coding Conventions

Testing Strategy

Deployment

Build docs developers (and LLMs) love

Base URL

Authentication

URL Conventions

Pagination

HTTP Status Codes

Error Response Format

DTO Validation

Swagger Documentation

Related Pages