glossary_api/README.md

# Glossary API

## Stack

- [Nest](https://github.com/nestjs/nest)
- TypeORM

## Project setup

```bash
$ npm install
```

## Running local infrastructure

To simplify development, all local infrastructure is handled with Docker. The folder `dev_infra` contains the following:

- `compose.yaml`: A Docker compose file that stands up a Postgres database and a pgAdmin instance to visualize.

To start up the local infrastructure, open a new terminal session, navigate to the `dev_infra` folder, and run the following command:

```bash
# start up the docker instances for the Postgres database and the pgAdmin interface
$ docker compose up

# use 'ctrl + c' on the keyboard to close the Docker view
```

Once finished, use the following command to tear down the local infrastructure:

```bash
# tear down the docker instances
$ docker compose down
```

### Authentication

To test authentication in development, a dev cognito pool was created. Its' important values are included in the `set-env.sh` file. The pool consists of the following users:

- email: jesse.desjardins@ccascoe.org, username: 5c6d4528-5021-704a-27fd-68342d44783b, password: DuckTester25!

An access token will be required to test the routes. A safe way of getting one is as follows:

1. Logging into the default [Cognito Login page](https://ca-central-1ea62zdmoc.auth.ca-central-1.amazoncognito.com/login/continue?client_id=7ph76km1h1v4vkt4rj9c3s4o6&redirect_uri=https%3A%2F%2Fd84l1y8p4kdic.cloudfront.net&response_type=code&scope=email+openid+phone) using that URL, as it has the `openid` scope included.

2. After logging in, the URL will have a `code` parameter appended at then end. Use that code in the following curl command:

```bash
 curl -X POST \
  https://ca-central-1ea62zdmoc.auth.ca-central-1.amazoncognito.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=7ph76km1h1v4vkt4rj9c3s4o6" \
  -d "code=<enter code here>" \
  -d "redirect_uri=https://d84l1y8p4kdic.cloudfront.net"
```

3. The curl command will return, among other things, an `access_token` value. That token will be valid for 1 hour and will work for manual tests of the API if included in all API calls.

#### Alternative ways of retrieving tokens

Using the bolow command will get a token from the AWS CLI, but it will not have the required "openId" scope and will fail authorization in the API:

```bash
aws cognito-idp admin-initiate-auth --user-pool-id "ca-central-1_ea62zDmOC" --client-id "7ph76km1h1v4vkt4rj9c3s4o6" --auth-flow "ADMIN_USER_PASSWORD_AUTH" --auth-parameters "USERNAME=5c6d4528-5021-704a-27fd-68342d44783b,PASSWORD=DuckTester25!"
```

### Database Migrations

Any time a change is made to a `.entity.ts` file, a new migration will need to be generated and added to the `appDataSource.ts` file. This ensures the API is refencing the most up-to-date (and valid!) database schema. These are the migration commands:

```bash
# generate migration
$ npm run db:gen_migration

# generate migration with a custom name
$ npm run db:gen_migration_named --name=<any_name_here>

# show migrations
$ npm run db:show_migrations

# run migrations
$ npm run db:run_migrations
```

**NOTE ON MIGRATIONS IN TYPEORM**: In order for any new migration to be considered in the `db:show_migrations` or `db:run_migrations` commands, they'll need to be added to the `appDataSource.ts` file, under the `migrations: []` option.

## Compile and run the project

```bash
# Set env variables, which default to local infrastructure
$ . ./set-env

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod
```

## Run tests

```bash
# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov
```

## Deployment

When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.

If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:

```bash
$ npm install -g @nestjs/mau
$ mau deploy
```

With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.

## Resources

Check out a few resources that may come in handy when working with NestJS:

- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).

## Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).

## License

Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).