Aller au contenu principal

REST API

The Ever Gauzy REST API follows standard HTTP conventions with OpenAPI 3.0 (Swagger) documentation auto-generated from NestJS decorators.

Conventions​

URL Structure​

{base_url}/api/{resource}
{base_url}/api/{resource}/{id}
{base_url}/api/{resource}/{id}/{sub-resource}

HTTP Methods​

MethodPurposeIdempotentRequest Body
GETRead resource(s)✅No
POSTCreate resource❌Yes
PUTFull update✅Yes
PATCHPartial update✅Yes
DELETERemove resource✅No

Resource Naming​

  • Resources use kebab-case: /api/time-off-request, /api/organization-project
  • Resource names are nouns, not verbs: /api/employees not /api/getEmployees
  • Sub-resources express relationships: /api/employee/{id}/statistics

CRUD Operations​

Create (POST)​

POST /api/employee
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "startedWorkOn": "2024-01-01",
  "userId": "user-uuid",
  "organizationId": "org-uuid"
}

Response: 201 Created

{
  "id": "employee-uuid",
  "firstName": "John",
  "lastName": "Doe",
  "startedWorkOn": "2024-01-01T00:00:00.000Z",
  "tenantId": "tenant-uuid",
  "organizationId": "org-uuid",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Read One (GET)​

GET /api/employee/{id}
Authorization: Bearer {token}

Response: 200 OK

{
  "id": "employee-uuid",
  "firstName": "John",
  "lastName": "Doe"
}

Read Many (GET)​

GET /api/employee?take=10&skip=0&order[createdAt]=DESC
Authorization: Bearer {token}

Response: 200 OK

{
  "items": [
    { "id": "...", "firstName": "John", "lastName": "Doe" },
    { "id": "...", "firstName": "Jane", "lastName": "Smith" }
  ],
  "total": 42
}

Update (PUT/PATCH)​

PUT /api/employee/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Updated"
}

Response: 200 OK

Delete (DELETE)​

DELETE /api/employee/{id}
Authorization: Bearer {token}

Response: 200 OK or 204 No Content

Query Parameters​

Pagination​

ParameterTypeDefaultDescription
takenumber10Number of records to return
skipnumber0Number of records to skip

Ordering​

GET /api/employee?order[createdAt]=DESC&order[firstName]=ASC

Relations​

Load related entities:

GET /api/employee?relations[]=user&relations[]=organization

Filtering​

GET /api/employee?where[isActive]=true&where[organizationId]=org-uuid

DTO Validation​

Request bodies are validated against Data Transfer Object (DTO) classes using class-validator:

export class CreateEmployeeDTO {
  @ApiProperty()
  @IsNotEmpty()
  @IsString()
  firstName: string;

  @ApiProperty()
  @IsNotEmpty()
  @IsString()
  lastName: string;

  @ApiProperty({ required: false })
  @IsOptional()
  @IsDateString()
  startedWorkOn?: string;

  @ApiProperty()
  @IsUUID()
  userId: string;
}

If validation fails, the API returns 400 Bad Request with details:

{
  "statusCode": 400,
  "message": ["firstName must be a string", "firstName should not be empty"],
  "error": "Bad Request"
}

Swagger Documentation​

Accessing Swagger​

Navigate to http://localhost:3000/swg for the interactive Swagger UI.

Swagger JSON​

Download the OpenAPI specification:

curl http://localhost:3000/swg-json > openapi.json

Decorators Used​

The API uses NestJS Swagger decorators to generate documentation:

@ApiTags('Employee')
@ApiOperation({ summary: 'Create a new employee' })
@ApiResponse({ status: 201, description: 'Employee created', type: Employee })
@ApiResponse({ status: 400, description: 'Validation error' })
@ApiBearerAuth()