API

The REST API is built with:

• NestJS
  • class-validator
  • jwks-rsa
• TypeORM with PostgreSQL (using version 14+)

Debugging: Start in dev mode in a terminal and attach to node process via command Debug: Attach to Node Process.

Access Local Swagger: API Documentation

REST API

For request samples, see ./api/**/*.http files. Those can be executed using REST Client extension in VSCode.

General URL nomenclature:

Verb	URL template	Payload	Description
GET	/api/entities	N/A	Get all resources of this 'entity'
POST	/api/entities	{ property1: 'value', property2: true }	New object for 'entity', returns the inserted entity
PUT	/api/entities/id	{ property1: 'value1', property2: false }	Update object
PATCH	/api/entities/id	{ property1: 'value2' }	Update object with only the properties provided
DELETE	/api/entities/id	N/A	Delete object, returns objects of same archive state as deleted
GET	/api/entities/id	N/A	Get object
PUT	/api/entities/id/archive	{ archived: true }	Change archive state of entity, returns updated object

The 'archive' example here is an example of operation and payload that can be provided having an effect on an entity. In this case it is different from a PATCH with { archive: true } because maybe we would prefer to change the archivedAt with a date instead of letting a client change/provide this value.

Authentication

Authentication is using JWT. It's a simple mechanism, it has its flaws, but for our purpose, we live with it.

See also: authentication

Cache

The cache for requests (using NestJS's cache manager)

To add support to cache, we need to use dependencies from:

import { CacheInterceptor, CacheModule } from '@nestjs/cache-manager';

At this date, the cache has been removed. It's causing some side effects with the use of Redux RTK. The web app is the main client using the API and by itself it has a cache mechanism client-side. When the RTK decides that the data should be updated (after a delete for example), the server returned the cached result and the data client-side was not updated.

See also: cache

Throttling

A throttling is used on the API to avoid abuse. For now it's a simple mecanism.

Entity creation with TypeORM

• Create en *.entity.ts class in domain/entities sub-directory of your module.
• Add this entity reference to entities's array in typeOrmConfig (file typeorm.config.ts).
• Add the entity reference in module's class decorator in the TypeOrmModule.forFeature's imports array.
• Proceed to migration

See also: database migration

Tests

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

See also

See ADR 004 - REST API