Express API

Express API

This API is currently under development with the goal of replace the ASP.NET API in the future.

As such, this page is an evolving document that will change over time.

The decision to replace the ASP.NET API was supported by the following goals:

• Modernize the PIMS API solution
• Standardize the technologies used in products across CITZ:IMB
• Increase the team's ability to support the application

Development Instructions

For detailed instructions on how to setup the Express API for development, please see the README file located in the /express-api directory.

Express

Express is a minimal and flexible Node.js web application framework that provides a robust set of features for building REST API servers.

It handles requests with a combination of routes, handlers, and middleware to return appropriate responses.

Here's an example of a combined route and handler to send hello world:

// respond with "hello world" when a GET request is made to the homepage
app.get('/', (req, res) => {
  res.status(200).send('hello world')
})

TypeORM

TypeORM is an object relational mapping (ORM) tool that helps facilitate the connection between the API service and a database.

It provides a unique way to specify entities in the database and gives developers a controlled and method of manipulating that data.

A short example of a an entity in TypeORM looks like this:

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm"

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    firstName: string

    @Column()
    lastName: string

    @Column()
    isActive: boolean
}

Accessing a user from that entity then looks like this:

const user = await dataSource
    .createQueryBuilder()
    .select("user")
    .from(User, "user")
    .where("user.id = :id", { id: 1 })
    .getOne()

Keycloak

Keycloak is a service that provides user authentication and role management.

Within the Government of British Columbia, it is consumed through the Pathfinder SSO service.

Using this, users can be authenticated and authorized by using either their IDIR login credentials or their BCeID.

Swagger

Swagger is an endpoint documentation solution that implements the OpenAPI Specification.

It allows developers to view and test application endpoints through their browser without the need for additional tools.

A link to the Swagger page for the Express API is available here, but developers experimenting with the API should use the Swagger page hosted by their local clone of PIMS or the Swagger page provided by the DEV environment.

Jest

Testing is primarily accomplished using the Jest test runner.

Jest provides a large suite of testing functions that assist developers in unit and integration testing.

For unit testing, sub-components can be mocked in order to test each parent component in isolation.

For integration testing, Jest pairs well with supertest to help automate the testing of endpoints.

An example of an integration test for the Express route above might look like this:

describe('GET /', function() {
  it('responds with hello world', function(done) {
    const response = await request(app)
      .get('/');
    expect(response.status).toEqual(200);
    expect(response.text).toEqual('hello world');
  });
});

File Structure

The file structure for this service is as follows:

/src
├── appDataSource.ts
├── constants
├── controllers
│   ├── administrativeAreas
│   ├── agencies
│   ├── buildings
│   ├── common
│   ├── healthController.ts
│   ├── index.ts
│   ├── lookup
│   ├── ltsa
│   ├── notifications
│   ├── parcels
│   ├── projects
│   ├── properties
│   ├── reports
│   ├── roles
│   ├── tools
│   └── users
├── express.ts
├── middleware
├── notificationTemplates
├── routes
├── server.ts
├── services
│   ├── agencies
│   ├── buildings
│   ├── ches
│   ├── geocoder
│   ├── keycloak
│   ├── ltsa
│   ├── notifications
│   ├── parcels
│   ├── projects
│   ├── properties
│   ├── roles
│   └── users
├── swagger
├── typeorm
│   ├── Migrations
│   │   └── Seeds
│   ├── Transformers
│   ├── entitiesIndex.ts
│   └── utilities
└── utilities