# Guide for Toto API Controller v11.0.0

## Changes in this version
Version 11.0.0 has introduced two major changes: 

1. Move to **Typescript**
2. Simplification of the Authentication Validation steps

## 1. Using the API Controller
The API Controller can be used as follows: 

### Import
Import through `import { TotoAPIController } from "toto-api-controller";`

### Instantiate
Instantiate through `const api = new TotoAPIController("your api name", new ControllerConfig())`. <br>
The instantiation requires that you have defined a `ControllerConfig` class that `implements TotoControllerConfig`.<br>
This class will thus have to define the following methods:
 * `async load()` that loads any configuration needed (e.g. secrets)
 * `getCustomAuthVerifier(): CustomAuthVerifier | undefined` that returns (optionally) a custom authentication verified that follows the `CustomAuthVerifier` interface
 * `getProps(): ValidatorProps` that returns the following properties, **all optional**: 
    * `noAuth`: default false, if set to true, the service will bypass the verification of the Authorization header. This means that the API will be **unauthenticated**. 
    * `noCorrelation`: default false, if set to true, the caller won't have to pass a `x-correlation-id` header
    * `minAppVersion`: default null, if set to a value, the caller will have to provide a `x-app-version` header and the API Controller will verify that the provided header value is greater or equal than this `minAppVersion`
 * `getExpectedAudience(): string` that returns the expected **Audience** in the `aud` field of the JWT token

### Register API Paths
To register an API path, add a line for each path: <br>
`api.path("GET", "/games", new GetGamesOverview())`

The `new GetGamesOverview()` instantiates a `TotoDelegate`. <br>
Toto Delegates have the responsibility to handle requests to a given path.<br>
They implement the method: <br>
`async do(req: Request, userContext: UserContext, execContext: ExecutionContext): Promise<any>`

#### UserContext
The variable `userContext` contains the following fields:
 * `userId`: the id of the user according to the Identity Provider
 * `email`: the user email
 * `authProvider`: a string identifying the IDP

### ExecutionContext
The variable `executionContext` contains the following: 
 * `logger`: a `TotoLogger` that can be used to log messages to the console out
 * `cid`: the correlation id
 * `appVersion`: the app version (content of the `x-app-version` header, if present)
 * `apiName`: the name of this API
 * `config`: the instance of the `TotoControllerConfig` used by this API

## Start
To start the API Controller, just add this: 
```
api.init().then(() => {
    api.listen()
});
```