LOCAL_DEVELOPMENT.MD

Running the App Locally

First, make sure you have Node.js (which includes npm). Then navigate to the project directory and install project dependencies by running npm install.

After dependencies have been installed, run npm run dev to start the app. Once the app has started, try going to localhost:3030 from a browser. When you're ready to start getting data, see the Retrieving Data and Modifying Flight Engine sections.

Retrieving Data

Once the app is running (either locally or in a cloud environment - e.g., your-app.herokuapp.com or localhost:3030) navigate to its URL in a browser and you should see a "👋". To start retrieving flight information, make a GET request to /flights with a date query parameter and a date value with the following format: YYYY-MM-DD. For example, your-app.herokuapp.com/flights?date=2020-01-01 will return flight details for January 1st, 2020. If you'd like to specify an origin or a destination, use the origin and/or destination query parameters with an airport code as the value; for example, your-app.herokuapp.com/flights?date=2020-01-01&origin=DFW&destination=LGA will retrieve flights from DFW to LGA on January 1st, 2020.

Explore the app with Postman

A quick way to start exploring the app is to use Postman. Download the app and import the Flight Engine.postman_collection.json Postman collection contained within this project. After importing, you can edit the collection and modify the baseURL variable if you've deployed to a cloud environment if needed.

The collection contains several example requests, including /flights and shows how to request data from the API, including the use of the date, origin, and destination query parameters.

Modifying Flight Engine

You can customize Flight Engine to tweak existing routes, add data, or even add new routes so it can be used as your app's backend.

Adding a new Route

If you want to create a new API route, use the app variable defined within/exported from src/app.ts and follow the documentation for Express.js to create a new listener. For example, you could create the /theMeaningOfLife endpoint by adding the following code to src/app.ts (at the bottom but above export default app;):

app.get('/theMeaningOfLife', (_: express.Request, res: express.Response): void => {
  res.send('42');
});

You could also create a new file and consume that route from within src/app.ts:

// src/theMeaningOfLife.ts
import express from 'express';

export default function theMeaningOfLife(_: express.Request, res: express.Response): void {
  res.send('42');
}

// src/app.ts
import theMeaningOfLife from './theMeaningOfLife';
// ...
app.use('/theMeaningOfLife', theMeaningOfLife);

Randomization via a Seed Value

In order to keep the app lightweight and eliminate the need for a database, this project uses seed randomization (credit to @JohnKahn for the amazing idea!). If you plan to modify routes that use flight data, make sure to read this content carefully as it is critical in order to maintain data integrity.

Here are some important things to note if you plan to modify the random data generation:

• After a Generator is initialized with a seed, the random method will generate random data each time it is called, however, this data generation is deterministic...
• Because this method of random generation is deterministic, the order and value of the "random" value sets generated by multiple calls to random for a given seed will always be the same
  • That was a lot... let's say we have generatorA and generatorB and each have been initialized with a seed value of RANDOMIZATION_IS_COOL!. If we call the random method of each generator (e.g., A1 and B1), the result will be the same (A1 === B1). If, however, we call the random method again, the new values will again be the same (A2 === B2) but they should differ from the first set of values generated by each of the generators (A1 !== A2 && B1 !== B2).
• Whenever a GET /flights call is performed, the app generates all flights for the specified date, regardless of the presence of origin and/or destination
  • If we only generate a subset of the data based on origin and/or destination, the order in which the flights generated for each O&D pair would differ and flight data would be different depending on the request parameters (e.g., flight 123 retrieved via/flights?date=2020-01-01 and /flights?date=2020-01-01&origin=DFW would differ). Here's an example:
    • random method calls 1-10 with a seed of 2020-01-01 will ALWAYS result in: [1, 7, 9, 1, 8, 4, 5, 7, 2, 3]
    • /flights?date=2020-01-01:
      1. Generate LGA flights (random calls 1-4)
      2. Generate MIA flights (random calls 6-7)
      3. Generate DFW flights (random calls 8-10), flight 123 was call 9 and got a random value of 2
    • /flights?date=2020-01-01&origin=DFW:
      1. Generate DFW flights (random calls 1-3), flight 123 was call 2 and got a random value of 7
    • Because the values are different, the data for flight 123 will not be the same for those two calls