COMP 20: Web Programming

Assignment 3: The Server for The Black Car Service

Due: Wednesday, April 12th

This assignment is worth 25 points. You must work on this assignment individually.



In Assignment 2, you sent your username, latitude, and longitude to a web application server (i.e.,, and it responded with a gob of data, where others in the class er I mean passengers or vehicles, in JSON format. In this assignment, you will write a web application that is almost exactly like that used for Assignment 2, and deploy it.

Using Heroku, Node.js with the Express web framework, and MongoDB, you are to build a web application server that maintains and serves locations of passengers and vehicles (username, latitude, and longitude) for a long period of time.

Getting Started

  1. For this assignment, you will not be using your private GitHub repository!
  2. Do Lab 8 ASAP. Use the web application you create in the lab for this assignment.
  3. You will need to use the mLab MongoDB plugin add-on for your web application. See Run heroku addons:create mongolab:sandbox inside of your Heroku app folder (the one you used for Lab 8). This will enable MongoDB for your web application on Heroku. There is a 496 MB limit for data storage, more than enough for our needs. If you forget to add a MongoDB plugin for your web application, your web application will return errors.

Data Description

Your web application shall work with two sets of data: vehicles and passengers. In MongoDB, a set of data is known as a collection. If you are familiar with relational databases, a collection is analogous to a "table". The collection contains a number of records, properly known as documents. If you are familiar with relational databases, a document is analogous to a "row".

Each document will have the data field _id (the document's unique field, primary key) created automatically.

The Keys for a Single Document in vehicles and passengers

The data that must be stored in one document (or record) in vehicles and passengers collections are:

Whitelist of all Vehicles

The following is the list of all the vehicles that were used in Assignment 2. Use this list to check if username is a driver / vehicle:

var vehicles = ['JANET','ilFrXqLz', 't4wcLoCT', 'WnVPdTjF', '1fH5MXna', '4aTtB30R', '8CXROgIF', 'w8XMS577', 'ZywrOTLJ', 'cQRzspF5', 'GSXHB9L1', 'TztAkR2g', 'aSOqNo4S', 'ImjNJW4n', 'svEQIneI', 'N10SCqi5', 'QQjjwwH2', 'H0pfmYGr', 'FyUHoAvS', 'bgULOMsX', 'OlOBzZF8', 'Ln7b7ODx', 'ZoxN11Sa', 'itShXf78', 'o6kJKzyI', 'pD0kGOax', 'njr1i7xM', 'wtDRzig8', 'l2r8bViT', 'oZn3b2OZ', 'ym2J1vil'];


Your web application shall have the following features or APIs (Application Programming Interfaces):

1. A POST /submit API

Returns a JSON string. Submits check-in from any domain. The required fields and exact field names for submission to this API are username, lat, and lng. Successful submission of these three pieces of data shall result in one entry into either the collection vehicles (if username is in the list above) or passengers (otherwise) in MongoDB.

If a submission is missing any one of the required fields, do not insert new record into the database and send the following JSON as the response: {"error":"Whoops, something is wrong with your data!"}.

Upon successful insertion of record into vehicles collection (i.e., username is a driver / vehicle), return a JSON string that is an object with the key passengers and the corresponding value is a list of all passengers who have requested a vehicle within the last five minutes. Example JSON response, same as the one seen in the Assignment 2 specification: {"passengers":[{"_id":"589bd3258451126182dfbc63","username":"dwR3TbOH","lat":20.3,"lng":20.4,"created_at":"2017-02-09T02:25:41.166Z"}]}

Upon successful insertion of record into passengers collection (i.e., username is NOT a driver / vehicle), return a JSON string that is an object with the key vehicles and the corresponding value is a list of all drivers / vehicles who have been seen within the last five minutes. Example JSON response, same as the one seen in the Assignment 2 specification: {"vehicles":[{"_id":"589bd30f8451126182dfbc62","username":"ym2J1vil","lat":10.1,"lng":10.2,"created_at":"2017-02-09T02:25:19.575Z"}]}

IMPORTANT: Cross-origin resource sharing must be enabled for this API, else data cannot be sent from another domain (i.e., your Assignment 2 map will not work).

Multiple check-ins for a username is NOT allowed. For all subsequent submissions for a given username, lat, lng, and created_at shall replace old entries in collection.

2. A GET /vehicle.json API

Returns the record for a given username as a JSON object if record exist in MongoDB collection vehicles. The mandatory parameter for this API is username. If the username query parameter is empty, not provided, or no results found, return empty JSON object {}.

Example output 1: GET /vehicle.json?username=ym2J1vil returns {"_id":"589bd30f8451126182dfbc62","username":"ym2J1vil","lat":10.1,"lng":10.2,"created_at":"2017-02-09T02:25:19.575Z"}

Example output 2: GET /vehicle.json?username=dwR3TbOH returns {} as dwR3TbOH is not a legitimate vehicle.

Example output 3: GET /vehicle.json returns {} as no username was given.

Cross-origin resource sharing must be enabled for this API else another another domain cannot retrieve data.

3. GET / - Home, the root, the index

Returns HTML. You may also use additional JavaScript and CSS, and you are free to design this page however you desire. Accessing this on a web browser (e.g., shall display list of all the passengers in the database in descending order by timestamp (that is, the last person who requested a vehicle is displayed first). username, and check-in timestamp must be displayed in addition to the location (latitude and longitude). Simply outputting JSON as the page is unacceptable. Example output: dwR3TbOH requested a vehicle at 10.1, 10.2 on 2017-02-09T02:25:19.575Z.


Please note that I did not mention a thing about security or error handling in the requirements. Authentication to this web application is not required. There is a reason for this, as you will see in Assignment 4.


  1. The Express web framework API reference (offcial)
  2. The nodemongoapp example I wrote
  3. Node.js + Express + Cross-Domain Scripting (Stack Overflow)
  4. Getting Started with MongoDB Development (official)
  5. Lab 8
  6. Getting Started with Node.js on Heroku - Provision a Database
  7. The Official MongoDB Node.JS Driver QUICK START
  8. The Official MongoDB Node.JS Driver Documentation

Testing Your Web Application


Each assignment and lab shall include a README file that describes the work. This description must:

  1. Identify what aspects of the work have been correctly implemented and what have not.
  2. Identify anyone with whom you have collaborated or discussed the assignment.
  3. Say approximately how many hours you have spent completing the assignment.
  4. Be written in either text format (README.txt) or in Markdown ( No other formats will be accepted. Please use all capital letters for README

Submitting the Assignment

  1. Push and deploy your app to Heroku.
  2. It is expected that you will use the same web app / repo from lab 8 for this assignment. If you are to create a new web app on Heroku for this assignment, you will need to add me as a collaborator (using my email address mchow[AT]cs[DOT]tufts[DOT]edu) for your web application in Heroku. You can do this by logging on to Heroku, go to the dashboard for your web application, under "Access", click on the "Add collaborator" button, enter my email address, and click "Save changes".