Technical Documentation

Description

This API provides the functionality described in the SERVICE.md and specified in the OpenAPI docs. It is built with the Business Functions Framework (BFF) tool chain described in the BFF User Docs.

Development Checklist

BFF operates under a shared responsibility model where you are responsible for the development and maintenance of the API. When extending this API:

1. prepare your local environment (see section below)
2. revise and update if necessary the SERVICE.md, README.md, and owner of the API
3. leverage the API dictionary when extending your API spec
4. update to the latest albus and hagrid versions
5. (re)generate the API microservice from the OpenAPI using albus by running albus generate -p <your_open_api_doc> -o <service_directory>
6. implement the business logic for your extension
7. (re)generate hagrid deployment artifacts by running hagrid init --overwrite --includeDockerfile and update the pipeline by running cd ci/ && make set-pipeline

A complete tutorial building an API E2E is provided in the BFF user docs.

Environment Requirements

Check the environment setup required in BFF user docs section Environment Setup.

Run the API Service Locally

This API is built using the NodeJS runtime. The package.json contains a set of scripts to build, lint, run, etc., the API locally. To run the service locally run yarn && ENV_VAR=bar ENV_VAR_2=bar2 yarn start

The server will be listening on the default url localhost:8080 You can check the health of the service in your browser under http://localhost:8080/vw-stm-booking-service/health

To comply to BFF Standards, the following endpoints are available next to the health check:

• http://localhost:8080/vw-stm-booking-service/portal/api
• http://localhost:8080/vw-stm-booking-service/portal/manual
• http://localhost:8080/vw-stm-booking-service/portal/changelog
• http://localhost:8080/vw-stm-booking-service/portal/risklog
• http://localhost:8080/vw-stm-booking-service/portal/config

Further scripts that can be used are

• Run linting: yarn lint
• Create an OSS-license-report from the dependencies: yarn license:report

Generated Source Code

As mentioned before, once your OpenAPI spec is modified, you should run albus generate -p <your_open_api_doc> -o <service_directory> to generate or regenerate the microservice. The following files are generated and should not be manually changed:

• src/generated
• src/middleware
• tsconfig.json
• .prettierrc
• .gitignore
• .eslintrc.json
• .eslintignore

Take into account that albus always regenerates these files or directories. The general recommendation is not to modify them. In case you do, that means that you will own that piece of code or configuration and will have to manually update it. Check albus help by running albus generate -h to take a look at the possibilities to customize which files to overwrite when regenerating.

API Tags

The complete info regarding tagging services in BFF can be found here.

Testing

The complete info regarding testing in BFF can be found here.

Unit Tests

Unit tests are your responsibility, as you own the business logic. The requirement is to have a 70% of unit test coverage, and these have to be developed right next to the typescript file that is being tested. For instance if you develop your business logic in src/my-logic/my-logic.ts, then the unit tests must be developed in src/my-logic/my-logic.spec.ts. Unit tests can be executed with yarn test.

API Tests

Albus generates API tests under src/api-tests using the example requests and responses provided in the OpenAPI spec. You must open the API tests and verify that these are correct or if further business logic is necessary. API tests can be run with STAGE=<stage> AWS_REGION=<AWS_REGION> API_KEY=<api_key> yarn test:e2e:stage, where stage is the stage you want to execute the API test logic against, e.g. local, dev, int, cons, prod. AWS_REGION is the region where your API is deployed, and API_KEY is the necessary API key to access the API.

Architecture

Technical Diagram

Here the technical architectural overview diagram of your service should be displayed.

Architectural Description

Here the written explanation of your architecture should be displayed.

Operational Information

Standard Monitoring and Logging

BFF APIs use Datadog for monitoring and logging. The BFF tech stack automatically integrates with Datadog. More info can be found here. APIs in BFF

• create standard alarms
• are shown in the BFF public datadog dashboard

Custom Dashboards and Monitors

Here you must include the dashboards and monitors that have been customly created for this API.

Incident Analysis and Process - Steps and Tips

Here you should provide steps and tips

1. to optimize the incident analysis
2. how and who to notify if the API is not working. For instance, include an email address or telephone number for 24/7 support

Contact

Please contact the API owner contact defined in the service.json.