SpokenAPI
The Spoken API resolves queries and mutations via graphql

# Development

[See here for running the entire application](../README.md#Development)
If you would just like to run the API, you can run `yarn docker:compose` from this folder.

An [Adminder](https://www.adminer.org/) instance is created through the normal docker setup to help debug/view what data is being added to the database during development. The instance is available at `localhst:8080` with the following credentials:

```
System: PostgreSQL
Server: database
Username: admin
Password: admin
Database: dev
```

The API playground will be available at `localhost:8000/api`.

This module also relies of an async job processor. To run the API locally outside of docker, those packages, must also be built.

## Seeding data

To seed dev data, you can run `yarn docker:seed:run`.

## To access an `@Authorized` query, you must:

1. Run this mutation (username and password are not validated in development, so anything works):

```gql
mutation {
  signIn(input: { username: "a", password: "b" }) {
    token
  }
}
```

2. On the bottom of the screen, tap HTTP Headers and paste in this:

```gql
{
  "authorization": "<YOUR_TOKEN_FROM_SIGN_IN_MUTATION>",
}
```

## Architecture

- Postgres is used to store data specific to this application
- Typeorm is used to connect to the postgres.

## Data Models (Entities)

Entities are the underlying models that describe both graphql objects and typeorm models. They are located in `src/entities`.

These files have many decorators because they're using both `typeorm` decorators (to describe data that gets stored in the database) and `type-graphql` to describe the objects that we resolve.

## GraphQL Resolvers

This API relies on [type-graphql](https://github.com/MichalLytek/type-graphql/), which simplifies GraphQL API development. Most of the logic of resolvers is found inside of the `src/resolvers` folder. In general, we want to resolve entities, but other resolvable types can be defined via `type-graphql`'s `@ObjectType` decorator.

We also encourage the convention of writing simple field resolvers to be located in the `src/entities` folder rather than in `src/resolvers`.

## REST API

This API relies on [tsoa](https://tsoa-community.github.io/docs/introduction.html), which simplifies generating routes and OpenAPI Specification (OAS) from your controllers and models. The controllers can be found in `src/routes/v0` and they're scoped by version, i.e, v0 in this case. You can generate the routes and OAS by exporting a controller from `src/routes/v0/index.ts` and running `yarn gen:swagger` from the api folder. After starting the server, you can view the swagger ui docs by vising http://localhost:8000/docs/rest.

### Authentication

This api relies on basic auth and you'll need to pass in an api key as username for basic auth to access its endpoints. You can generate an api key by hitting `POST /v0/api-keys` and using the root id as username and root secret as password for basic auth. In development, the root id is `development` and the root secret is `development`.

## Testing 🧪

This package uses [Jest](https://jestjs.io) for testing. It also utilizes [ts-jest](https://kulshekhar.github.io/ts-jest/docs), a helper library to improve Jest testing in Typescript.
These tests are database enabled, so to run the test database (which will not impact your development database) via docker, run `yarn docker:testdb`. Then in a separate terminal, run `yarn test` or `yarn test:watch`.

## Services

# Deployment

This service is deployed automatically via the files in `scripts/deploy`.
[Learn more](scripts/deploy/README.md)