vw-stm-booking-service v0.0.1
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:
- prepare your local environment (see section below)
- revise and update if necessary the SERVICE.md, README.md, and owner of the API
- leverage the API dictionary when extending your API spec
- update to the latest albus and hagrid versions
- (re)generate the API microservice from the OpenAPI using albus by running
albus generate -p <your_open_api_doc> -o <service_directory>
- implement the business logic for your extension
- (re)generate hagrid deployment artifacts by running
hagrid init --overwrite --includeDockerfile
and update the pipeline by runningcd 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
- to optimize the incident analysis
- 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
.
1 year ago