Flights Microservice

Get flight details

• Input: flight_no, departure_local_date_time (ISO8601 format, and in local time zone)

• Response: unique flight_id identifying a specific flight on a specific date. In practice, this endpoint will very likely return other flight-related fields, but those are irrelevant for our context, so we are skipping over them.

Get flight seating: a diagram of seats on a flight

• Input: flight_id

• Response: SeatMap object in JSON format ¹

Reservations Microservice

Query Already reserved Seats on a Flight

• Input: flight_id

• Response: list of already-taken seat numbers, each seat number is in format like “2A”

Reserve a seat on a flight

• Input: flight_id, customer_id, seat_num

• Expected Outcome: seat is reserved and unavailable to others, or an error fired if the seat was unavailable

• Response: Success (200 Success) or Failure (403 Forbidden)

As discussed in Chapter 6, the beauty of writing-out actions and queries is that they bring us much closer to being able to create technical specs of the services than when jobs are presented in their business-oriented, jobs (JTBD) format.

Now that we have the actions and queries for our microservices, we can proceed with describing the microservices we intend to build in a standard format. In our case we build RESTful microservices and describe them with an Open API Spec. Let’s see, in the next section, what this spec for our two microservices could look like.

Designing Open API Spec

Based on the query and commands spec we just designed, translating it into an Open API spec is not a big deal and it would probably look something like the following for the flights microservice endpoints:

  openapi: 3.0.0
  info:
    title: Flights Management Microservice API
    description: |
      API Spec for Fight Management System
    version: 1.0.1
  servers:
    - url: http://api.example.com/v1
      description: Production Server
  paths:
    /flights:
      get:
        summary: Look Up Flight Details with Flight No and Departure Date
        description: |
          Lookup flight details, such as: the unique flight_id used by the
          rest of the Flights management endpoints, flight departure and
          arrival airports.

          Example request:
          ```
            GET http://api.example.com/v1/flights?
                flight_no=AA2532&departure_date_time=2020-05-17T13:20
          ```
        parameters:
          - name: flight_no
            in: query
            required: true
            description: Flight Number.
            schema:
              type : string
            example: AA2532
          - name: departure_date_time
            in: query
            required: true
            description: Date and time (in ISO8601)
            schema:
              type : string
            example: 2020-05-17T13:20


        responses:
          '200':    # success response
            description: Successful Response
            content:
              application/json:
                schema:
                  type: array
                  items:
                    type: object
                    properties:
                      flight_id:
                        type: string
                        example: "edcc03a4-7f4e-40d1-898d-bf84a266f1b9"
                      origin_code:
                        type: string
                        example: "LAX"
                      destination_code:
                        type: string
                        example: "DCA"

                  example:
                    flight_id: "edcc03a4-7f4e-40d1-898d-bf84a266f1b9"
                    origin_code: "LAX"
                    destination_code: "DCA"

    /flights/{flight_no}/seat_map:
      get:
        summary: Get a seat map for a flight
        description: |
          Example request:
          ```
            GET http://api.example.com/
                v1/flights/AA2532/datetime/2020-05-17T13:20/seats/12C
          ```
        parameters:
          - name: flight_no
            in: path
            required: true
            description: Unique Flight Identifier
            schema:
              type : string
            example: "edcc03a4-7f4e-40d1-898d-bf84a266f1b9"

        responses:
          '200':    # success response
            description: Successful Response
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    Cabin:
                      type: array
                      items:
                        type: object
                        properties:
                          firstRow:
                            type: number
                            example: 8
                          lastRow:
                            type: number
                            example: 23
                          Wing:
                            type: object
                            properties:
                              firstRow:
                                type: number
                                example: 14
                              lastRow:
                                type: number
                                example: 22
                          CabinClass:
                            type: object
                            properties:
                              CabinType:
                                type: string
                                example: Economy
                          Column:
                            type: array
                            items:
                              type: object
                              properties:
                                Column:
                                  type: string
                                  example: A
                                Characteristics:
                                  type: array
                                  example:
                                    - Window
                                  items:
                                    type: string
                          Row:
                            type: array
                            items:
                              type: object
                              properties:
                                RowNumber:
                                  type: number
                                  example: 8
                                Seat:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      premiumInd:
                                        type: boolean
                                        example: false
                                      exitRowInd:
                                        type: boolean
                                        example: false
                                      restrictedReclineInd:
                                        type: boolean
                                        example: false
                                      noInfantInd:
                                        type: boolean
                                        example: false
                                      Number:
                                        type: string
                                        example: A
                                      Facilities:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            Detail:
                                              type: object
                                              properties:
                                                content:
                                                  type: string
                                                  example: LegSpaceSeat

You can render the Open API Spec with a number of editors, for instance Swagger Editor-rendering of the above spec looks like Figure 10-2

Figure 10-2. Open API Spec for ms-flights rendered with Swagger Editor

Please note that for demonstration purposes, here we are using SeatMap object structure that mimics the one in Sabre’s SeatMap API – the gold standard of the industry. If you were really building a commercial API, you would design your own implementation or acquire a permission for reuse from the original author of the design.

Similarly to the Open API Spec of the flights microservice, the designs for the endpoints of the reservation system would be something along the lines of:

  openapi: 3.0.0
  info:
    title: Seat Reservation System API
    description: |
      API Spec for Fight Management System
    version: 1.0.1
  servers:
    - url: http://api.example.com/v1
      description: Production Server
  paths:
    /reservations:
      get:
        summary: Get Reservations for a flight
        description: |
          Get all reservations for a specific flight
        parameters:
          - name: flight_id
            in: query
            required: true
            schema:
              type: string
        responses:
          '200':    # success response
            description: Successful Response
            content:
              application/json:
                schema:
                  type: array
                  items:
                    type: object
                    properties:
                      seat_no:
                        type: string
                        example: "18F"
                  example:
                    - { seat_no: "18F" }
                    - { seat_no: "18D" }
                    - { seat_no: "15A" }
                    - { seat_no: "15B" }
                    - { seat_no: "7A" }
      put:
        summary: Reserve or cancel a seat
        description: |
          Reserves a seat or removes a seat reservation
        requestBody:
          required: true
          content:
            application/json:
                schema:
                  type: object
                  properties:
                    flight_id:
                      description: Flight's Unique Identifier.
                      type : string
                      example: "edcc03a4-7f4e-40d1-898d-bf84a266f1b9"
                    customer_id:
                      description: Registered Customer's Unique Identifier
                      type : string
                      example: "2e850e2f-f81d-44fd-bef8-3bb5e90791ff"
                    seat_num:
                      description: seat number
                      type: string
                example:
                  flight_id: "edcc03a4-7f4e-40d1-898d-bf84a266f1b9"
                  customer_id: "2e850e2f-f81d-44fd-bef8-3bb5e90791ff"
                  seat_num: "8D"
        responses:
          '200':
            description: |
              Success.
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    status:
                      type: string
                      enum: ["success", "error"]
                      example:
                        "success"
          '403':
            description: seat(s) unavailable. Booking failed.
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    error:
                      type: string
                    description:
                      type: string
                  example:
                    error: "Could not complete reservation"
                    description: "Seat already reserved. Cannot double-book"

Now that we have our service designs and the corresponding Open API specs, it is time to proceed to the last step in the SEED(S) process: writing the code for the microservices.

As we implement the Flights and Reservations microservices, we will practice the principles discussed earlier in this book. Specifically: we will use different tech stacks for these services, so we can demonstrate our ability of supporting heterogeneous implementation. Reservations microservice will be implemented in Python and Flask, while Flights microservice will be implemented in Node/Express.js.

Redis For the Reservations Data Model

In the reservations system, we need to be able to capture a set of seat reservations for a flight, and reserve a seat if it is not already reserved. Redis has a perfect, simple data-structure that fits very well the use-case: Hashes. We can have a hash for each flight_id (specific flight) where keys of the hash are the seat numbers on the flight and the value is the customer_id that seat is already reserved for. Redis has commands to set a new value in a hash, get all set values (for when we need to know all reserved seats), and very conveniently: a command that allows us to set value only if the value for the same key (seat) is not already set. That’s perfect for us since we typically do not want to allow double-booking a seat on a flight.

Let’s see an example of reserving several seats on a flight uniquely identified with the flight id: 40d1-898d-bf84a266f1b9:

> HSETNX flight:40d1-898d-bf84a266f1b9 12B b4cdf96e-a24a-a09a-87fb1c47567c
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 12C e0392920-a24a-b6e3-8b4ebcbe7d5c
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 11A f4892d9e-a24a-8ed1-2397df0ddba7
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 3A 017d40c6-a24b-b6d7-4bb15d04a10b
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 3B 0c27f7c8-a24b-9556-fb37c840de89
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 22A 0c27f7c8-a24b-9556-fb37c840de89
(integer) 1
> HSETNX flight:40d1-898d-bf84a266f1b9 22B 24ae6f02-a24b-a149-53d7a72f10c0
(integer) 1

Let’s see how we would get all of the occupied seats:

> HKEYS flight:40d1-898d-bf84a266f1b9
1) "12B"
2) "12C"
3) "11A"
4) "3A"
5) "3B"
6) "22A"
7) "22B"

If we wanted to get both keys and values, we can also do that:

> HGETALL flight:40d1-898d-bf84a266f1b9
 1) "12B"
 2) "b4cdf96e-a24a-a09a-87fb1c47567c"
 3) "12C"
 4) "e0392920-a24a-b6e3-8b4ebcbe7d5c"
 5) "11A"
 6) "f4892d9e-a24a-8ed1-2397df0ddba7"
 7) "3A"
 8) "017d40c6-a24b-b6d7-4bb15d04a10b"
 9) "3B"
10) "0c27f7c8-a24b-9556-fb37c840de89"
11) "22A"
12) "0c27f7c8-a24b-9556-fb37c840de89"
13) "22B"
14) "24ae6f02-a24b-a149-53d7a72f10c0"

Let’s now see what happens if we try to double-book an already reserved seat, such as 12C:

> HSETNX flight:40d1-898d-bf84a266f1b9 12C 083a6fc2-a24d-889b-6fc480858a38
(integer) 0

Please notice how the response to this command is (integer) 0 instead of the (integer) 1 we had gotten for earlier HSETNX commands. This indicates that zero fields were actually updated and that is because 12C had already been reserved.

As you can see, choosing Redis as the data store for ms-reservations has made the implementation easy and natural. We were able to use well-fitting data structures, such as HSET, that meet our needs effortlessly and elegantly. The HSETNX command allowed us to avoid accidental double-bookings in a way that is reliable and straightforward.

Redis is a fantastic key/value store and it can be used in a wide variety of use-cases. Which is why it has a huge fan base among programmers, however it is not going to be the perfect database for every single use-case we run into. Sometimes we may have data needs that are better met by other, popular databases.

To demonstrate this, in the next section, we will implement the data for the ms-flights microservice using a traditional, SQL database.

MySQL Data Model for the Flights Microservice

The first data-model we need here should contain seat maps. As we saw in the OpenAPI spec for the Flights microservice, the seat map is a complex JSON object. MySQL can be a better storage for such data than standard Redis. As of MySQL 5.7.8, MySQL has a robust, native support for JSON data types. This support has expanded and improved in the latest, 8.x version of MySQL. It now also supports in-place, atomic updates of JSON values and JSON Merge Patch syntax. In comparison, Redis only supports JSON with a RedisJSON module that doesn’t come pre-built with the standard Redis distribution.

A well-implemented JSON data type provides tangible advantages compared to storing JSON data in a string column: validation of JSON documents during inserts, internally-optimized binary storage, ability to look up sub-objects and nested values directly by a key, etc.

Additionally, in the lookup endpoint we need to query data by two fields: flight_no and datetime. A relational database is more natural structure for such queries. In Redis, we would probably need to create a compound field to achieve the same. All-in-all, while technically we could implement this service with Redis as well, there are reasons to choose MySQL over it and it also helps us demonstrate usage of different databases for different services. Real-life situations will obviously be more complex, with more aspects to consider.

Let’s look at the seat_maps table:

CREATE TABLE `seat_maps`  (
  `flight_no` varchar(10) NULL,
  `seat_map` json NULL,
  `origin_code` varchar(10) NULL,
  `destination_code` varchar(10) NULL,

  PRIMARY KEY(`flight_no`)
);

Another table we need is the mapping of flight_ids with flight_no’s and datetimes. Creation script for this table may look something like the following:

CREATE TABLE `flights`  (
  `flight_id` varchar(36) NOT NULL,
  `flight_no` varchar(10) NULL,
  `flight_date` datetime(0) NULL,

  PRIMARY KEY (`flight_id`),
  INDEX `idx_flight_date`(`flight_no`, `flight_date`)

  FOREIGN KEY(flight_no)
    REFERENCES seat_maps(flight_no)
);

Let’s insert our first sample seat map:

INSERT INTO `seat_maps`(`flight_no`, `seat_map`, `origin_code`, `destination_code`) VALUES ('AA2532', '{"Cabin": [{"Row": [{"Seat": [{"Number": "A", "Facilities": [{"Detail": {"content": "LegSpaceSeat"}}], "exitRowInd": false, "premiumInd": false, "noInfantInd": false, "restrictedReclineInd": false}], "RowNumber": 8}], "Wing": {"lastRow": 22, "firstRow": 14}, "Column": [{"Column": "A", "Characteristics": ["Window"]}], "lastRow": 23, "firstRow": 8, "CabinClass": {"CabinType": "Economy"}}]}', 'LAX', 'DCA');

Once we have the proper JSON value in the database, we can easily, select specific values in it or filter by specific values. For instance:

select seat_map->>"$.Cabin[0].firstRow" from seat_maps

Now that we have a working data model for both of our microservices, we can dive deeper into the implementation of the code for them.

The Code Behind the Flights Microservice

To use Nodebootstrap for jump-starting a Node/Express microservice, you can either install its bootstraper with node install -g nodebootstrap, if you already have Node available on your system, or just clone the provided Github template repository at: https://github.com/inadarei/nodebootstrap-microservice

While the former may be somewhat easier, we will do the latter since we do not want to assume that you had to set up Node on your system. Go ahead and click on “Use Template” at the nodebootstrap-microservice’s main repo page:

Once you have created a new repo for ms-flights microservice, at the destination of your choosing, let’s check it out on your developer machine and start modifying things, writing code.

One of the nice things about the Nodebootstrap template is that it comes with full support for an Open API Spec of the microservices. Let’s take the spec we designed earlier and put it into docs/api.yml file, replacing the sample spec we already find there. Make sure you are in the docs sub-folder and run make start:

→ make start
docker run -d --rm --name ms-nb-docs -p 3939:80 -v 
ms-flights/docs/api.yml:/usr/share/nginx/html/swagger.yaml 
-e SPEC_URL=swagger.yaml redocly/redoc:v2.0.0-rc.8-1
49e0986e318288c8bf6934e3d50ba93537ddf3711453ba6333ced1425576ecdf
server started at: http://0.0.0.0:3939

which will render the spec to a beautiful HTML template and make it available at http://0.0.0.0:3939. The rendering will probably look like something at the following screenshot:

Nodebootstrap microservice comes with a sample “users” module. It’s located under lib/users folder. Since we don’t need a user management module and need a flights management one, let’s rename that folder to “flights” and delete another default module: lib/homedoc as we are not going to need that one, as well. When you remove the lib/homedoc folder you need to also remove its plug from the appConfig.js in the root folder, around line 24 that reads something like:

  app.use('/',      require('homedoc')); // attach to root route

Likewise, change the hookup for flights module, in the same file so that line .. reads like:

app.use('/flights', require('flights')); // attach to sub-route

Once you are done making these modifications, edit the lib/flights/controllers/mappings.js file so it reads like the following:

const {spieler, check, matchedData, sanitize} = require('spieler')();

const router      = require('express').Router({ mergeParams: true });
const actions     = require('./actions');

const log = require("metalogger")();

const flightNoValidation = check('flight_no',
  'flight_no must be at least 3 chars long and contain letters and numbers')
  .exists()
  .isLength({ min: 3 })
  .matches(/[a-zA-Z]{1,4}d+/)

const dateTimeValidation = check('departure_date_time',
  'departure_date_time must be in YYYY-MM-ddThh:mm format')
  .exists()
  .matches(/d{4}-d{2}-d{2}Td{2}:d{2}/)


const flightsValidator = spieler([
  flightNoValidation,
  dateTimeValidation
]);
const seatmapsValidator = spieler([
  flightNoValidation
]);


router.get('/', flightsValidator, actions.getFlightInfo);
router.get('/:flight_no/seat_map', seatmapsValidator, actions.getSeatMap);

module.exports = router;

As you can see, in this file we are setting up routes for our two main endpoints and validators that ensure that our input parameters are present, as well as properly formatted. When they are not, Nodebootstrap also has standard error messaging to let the client know.

Let’s now implement some logic. First we need to create MySQL tables and some sample data. As you may guess Nodebootstrap provides an easy solution for this as well, in the form of database migrations - scripts that codify database modifications and allows you to apply them in any environment, later.

We can create several database migrations with some make commands, as follows:

→ make migration-create name=seat-maps
docker-compose -p msupandrunning up -d
ms-flights-db is up-to-date
Starting ms-flights ... done
docker-compose -p msupandrunning exec ms-flights
  ./node_modules/db-migrate/bin/db-migrate create seat-maps --sql-file
[INFO] Created migration at /opt/app/migrations/20200602055112-seat-maps.js
[INFO] Created migration up sql file at
  /opt/app/migrations/sqls/20200602055112-seat-maps-up.sql
[INFO] Created migration down sql file at
  /opt/app/migrations/sqls/20200602055112-seat-maps-down.sql
sudo chown -R $USER ./migrations/sqls/
[sudo] password for irakli:

→ make migration-create name=flights
docker-compose -p msupandrunning up -d
ms-flights-db is up-to-date
ms-flights is up-to-date
docker-compose -p msupandrunning exec ms-flights
  ./node_modules/db-migrate/bin/db-migrate create flights --sql-file
[INFO] Created migration at /opt/app/migrations/20200602055121-flights.js
[INFO] Created migration up sql file
  at /opt/app/migrations/sqls/20200602055121-flights-up.sql
[INFO] Created migration down sql file
  at /opt/app/migrations/sqls/20200602055121-flights-down.sql
sudo chown -R $USER ./migrations/sqls/

→ make migration-create name=sample-data
docker-compose -p msupandrunning up -d
ms-flights-db is up-to-date
ms-flights is up-to-date
docker-compose -p msupandrunning exec ms-flights
  ./node_modules/db-migrate/bin/db-migrate create sample-data --sql-file
[INFO] Created migration at
  /opt/app/migrations/20200602055127-sample-data.js
[INFO] Created migration up sql file at
  /opt/app/migrations/sqls/20200602055127-sample-data-up.sql
[INFO] Created migration down sql file at
  /opt/app/migrations/sqls/20200602055127-sample-data-down.sql
sudo chown -R $USER ./migrations/sqls/

After which we should open the the corresponding sql files and insert following content into each one of them:

CREATE TABLE `seat_maps` (
  `flight_no` varchar(10) NOT NULL,
  `seat_map` json NOT NULL,
  `origin_code` varchar(10) NOT NULL,
  `destination_code` varchar(10) NOT NULL,
  PRIMARY KEY (`flight_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

CREATE TABLE `flights`  (
  `flight_id` varchar(36) NOT NULL,
  `flight_no` varchar(10) NOT NULL,
  `flight_date` datetime(0) NULL,

  PRIMARY KEY (`flight_id`),

  FOREIGN KEY(`flight_no`)
        REFERENCES seat_maps(`flight_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO `seat_maps`
VALUES ('AA2532', '{"Cabin": [{"Row": [{"Seat": [{"Number": "A",
        "Facilities": [{"Detail": {"content": "LegSpaceSeat"}}],
        "exitRowInd": false, "premiumInd": false, "noInfantInd": false,
        "restrictedReclineInd": false}], "RowNumber": 8}],
        "Wing": {"lastRow": 22, "firstRow": 14},
        "Column": [{"Column": "A", "Characteristics": ["Window"]}],
        "lastRow": 23, "firstRow": 8,
        "CabinClass": {"CabinType": "Economy"}}]}', 'LAX', 'DCA');

Once you have these files, you can either just restart the project with make restart and the migrations will be automatically applied (the new ones get applied at every project start to keep various installation consistent), or you can explicitly run a task to apply migrations with: make migrate

For the rest of the modifications, you will want to:

1. Change ms-nodebootstrap-example with ms-flights in a variety of files, if you didn’t install the project with the nodebootstrap utility and just cloned the repo (former approach does renaming for you)

2. Modify the rest of the source code to implement the flights and seat_maps endpoints and hook them up with the database.

You can also see a working version of the sample ms-flights at: https://github.com/implementing-microservices/ms-flights

When everything is working you should be able to access your /flights endpoint locally at a URL like:

http://0.0.0.0:5501/flights?flight_no=AA34&departure_date_time=2020-05-17T13:20

and the seat_maps endpoint at a URL like:

http://0.0.0.0:5501/flights/AA2532/seat_map

Please check-out all of the makefile targets, such as testing one to get a sense of the user experience provided by the template project and what kind of facilities you should strive to provide to your developers with your templates. For the make test to work there’re additional modifications required, related to us deleting functionality from the sample project. We aren’t covering those changes, in detail, here, so it’s the best to just check out the https://github.com/implementing-microservices/ms-flights repo, which has every modification required. Feel free to submit bug requests, if you run into any problems.

// For Liveness Probe, defaults may be all you need.
const livenessCheck = healthcheck({"path" : "/ping"});
app.use(livenessCheck.express());

// For readiness check, let's also test the DB
const check = healthcheck();
const AdvancedHealthcheckers = require('healthchecks-advanced');
const advCheckers = new AdvancedHealthcheckers();
// Database health check is cached for 10000ms = 10 seconds!
check.addCheck('db', 'dbQuery', advCheckers.dbCheck,
  {minCacheMs: 10000});
app.use(check.express());

async dbCheck() {
  const start = new Date();
  const conn = await db.conn();
  const query = 'select count(1) from seat_maps';
}

{
  "details": {
    "db:dbQuery": {
      "status": "pass",
      "metricValue": 15,
      "metricUnit": "ms",
      "time": "2020-06-28T22:32:46.167Z"
    }
  },
  "status": "pass"
}

{ "status": "pass" }