SpokenAPI The Spoken API resolves queries and mutations via graphql

Development

See here for running the entire application If you would just like to run the API, you can run yarn docker:compose from this folder.

An Adminder 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):

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

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

{
  "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, 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, 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 for testing. It also utilizes ts-jest, 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