tms-customer-portal-api v1.0.0

tms-customer-portal-api

Customer Portal API

• Local development using Docker image of this service
• Making changes to this service
• Security
• Build process
• VS Code config

Local development using Docker image of this service

To use this web service in your local Docker environment, add the following to docker-compose.yml:

  tms-customer-portal-api:
    image: 'casestack/tms-customer-portal-api:stage'
    ports:
      - '40407:40404'
    depends_on:
      - mongodb
    labels:
      - traefik.enable=false
    environment:
      - ENVIRONMENT=DEV
      - USER=vagrant

The Swagger UI should be available at http://home.devbox:40407/v1/_swagger, assuming the default Vagrant configuration is used.

Making changes to this service

To start making changes to this service, clone this repository and add the following entry to docker-compose.yml:

  tms-customer-portal-api:
    image: 'casestack/node-service:1'
    ports:
      - '40407:40404'
    depends_on:
      - mongodb
    labels:
      - traefik.enable=false
    environment:
      - ENVIRONMENT=DEV
      - USER=vagrant
    command: 'yarn start:dev'
    volumes:
      - >-
        /home/vagrant/casestack/<path to tms-customer-portal-api>:/opt/cs-service
      - '$HOME/.npmrc:/root/.npmrc'

Using the above configuration, the Swagger UI should be available at http://home.devbox:40407/v1/_swagger, assuming the default Vagrant configuration is used.

Security

Endpoints that start with /secure require an HTTP header api_key whose value is the JSON string that contains brokerageId and whatever else is required by that endpoint (perhaps customerId, shipperId, etc.). This helps avoid passing these as parameters to the endpoints via query strings or paths. See app/src/middleware/tsoa/authentication.ts for details of how security is done.

When using Swagger UI, click on the red icon with exclamation point ! to enter the JSON string. An example JSON string is:

{
    "brokerageId": "brokerage id value"
}

Build process

The app uses koa with routes to controllers auto-generated from TypeScript's decorators in the *Controller class. The routes are generated by tsoa according to the template app/src/routes/koa-template/routes.txt.

After the build, swagger.json is also auto-generated by tsoa. The JSON is transformed to YAML by json2yaml for Swagger UI.

The file tsoa/v1.json defines how tsoa should generate the routes.ts and swagger.json.

VS Code config

Prettier and imports sorting

• Install this VS Code plugin for Prettier
• Put the following settings to .vscode/settings.json so that Prettier and import sorting are run per file save

  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }