2017S v1.1 (2/25/2017) 3166
CS261 Semester Project
Assignment 3: Database Access in Node
This assignment extends assignment 2 with some new requirements. Refer to the assignment 2
document for the explanation of concepts like API arguments and authentication. All of the
existing API features of your assignment 2 app need to continue to function and will be tested
again as part of grading this assignment.
SSL
You will receive an SSL certificate for your server, along with instructions on how to install the
certificate in Nginx. You’ll need to follow those instructions so that Nginx terminates the SSL
connection and forwards that information on to your app, then your app will need to enforce the
SSL requirement mentioned in assignment 2 (by returning an error when certain API methods
are called over non-encrypted connections).
Two Servers
Deploy your assignment 3 app onto two servers, and configure your load balancer to split traffic
between them. We will run a load test of your app as part of grading, and will expect to see
performance that indicates two servers running.
GitHub Repo
Your app needs to be committed to a GitHub repo. This will make deploying to multiple app
servers far easier, and will be used as part of grading.
The repo should be private and Steph and Johannes need to be added as collaborators. Their
GitHub usernames are stebee and JohannesMP
Example Repo
If you’re happy with your work on assignment 2, you should build assignment 3 off of that.
Otherwise, you are allowed (but not required) to start assignment 3 from this ‘known good’
project: https://github.com/stebee/CS261Assignment2
Download as zip, create a new repo in GitHub’s web UI and run the following in the repo folder:
git init && git add -A
git commit -m “initial commit”
git remote add origin https://github.com/
git push -u origin master
Unit Tests
As with assignment 2, you will be graded using the unit tests in this repository:
https://github.com/stebee/cs261tests
If you find any errors or notice edge cases that are not yet tested, feel free to file pull requests.
Useful contributions will be rewarded with extra credit.
https://github.com/stebee/CS261Assignment2
https://github.com/stebee/cs261tests
2017S v1.1 (2/25/2017) 3266
API Endpoints
Items: Create
Path: /api/v1/items/create
Requires Authentication?: Yes
Read-only?: No
Parameters:
• shortname: A short, enum-like identifier for the item. This field exists to simply client
development by providing an ID-like value that is guaranteed stable (unlike actual ID
values, which almost certainly change between development, staging and production).
The field must be unique; if the requested shortname already exists, fail with
“shortname”: “Already taken”.
Response Fields:
• id: The ID of the item.
• shortname: The shortname of the item.
Items: Update
Path: /api/v1/items/:id/update
Requires Authentication?: Yes
Read-only?: No
Parameters:
• id: The ID of the item.
• name [optional]: The name of the item.
• description [optional]: The description of the item.
• isStackable [optional]: Whether the item is a discrete entity (such as a weapon or a ship)
or is grouped into quantities (such as ammo or currency). Defaults to false.
• attributes [optional]: An arbitrary JSON object of properties. The meaning of this object is
only relevant to the client; the server API treats it as opaque.
Note that shortnames may not be edited once created.
Response Fields:
• id: The ID of the item.
• name: The name of the item, if modified.
• description: The description of the item, if modified.
• isStackable: The isStackable property, if modified.
• attributes: The attributes object, if modified.
2017S v1.1 (2/25/2017) 3366
Items: Get
Path: /api/v1/items/:id/get
Requires Authentication?: No
Read-only?: Yes
Parameters:
• id: The ID of the item.
Response Fields:
• id: The ID of the item.
• shortname: The shortname of the item.
• name: The name of the item. If no name has been set, this defaults to the shortname.
• description: The description of the item. If no description has been set, this defaults to
blank.
• isStackable: Whether the item is a discrete entity (such as a weapon or a ship) or is
grouped into quantities (such as ammo or currency). Defaults to false.
• attributes: An arbitrary JSON object of properties. The meaning of this object is only
relevant to the client; the server API treats it as opaque. Defaults to empty (“{}”).
Items: Find
Path: /api/v1/items/find
Requires Authentication?: No
Read-only?: Yes
Parameters:
• shortnames: An array of shortnames values to look up.
Response Fields:
• items: An array of Item objects. This array is parallel to the shortnames parameter array.
If a particular shortname does not map to an item, its entry is an empty object (“{}”).
o id: The ID of the item.
o shortname: The shortname of the item.
o name: The name of the item. If no name has been set, this defaults to the
shortname.
o description: The description of the item. If no description has been set, this
defaults to blank.
o isStackable: Whether the item is a discrete entity (such as a weapon or a ship) or
is grouped into quantities (such as ammo or currency). Defaults to false.
o attributes: An arbitrary JSON object of properties. The meaning of this object is
only relevant to the client; the server API treats it as opaque. Defaults to empty
(“{}”).
2017S v1.1 (2/25/2017) 3466
Items: List
Path: /api/v1/items/list
Requires Authentication?: No
Read-only?: Yes
Parameters: None
Response Fields:
• items: An array of Item objects:
o id: The ID of the item.
o shortname: The shortname of the item.
o name: The name of the item. If no name has been set, this defaults to the
shortname.
o description: The description of the item. If no description has been set, this
defaults to blank.
o isStackable: Whether the item is a discrete entity (such as a weapon or a ship) or
is grouped into quantities (such as ammo or currency). Defaults to false.
o attributes: An arbitrary JSON object of properties. The meaning of this object is
only relevant to the client; the server API treats it as opaque. Defaults to empty
(“{}”).
Inventory: Create
Path: /api/v1/users/:userid/inventory/create
Requires Authentication?: Yes
Read-only?: No
Parameters:
• userid: The ID of the user who will receive the created items.
• items: An array of items to create:
o itemid [optional]: The ID of the item.
o shortname [optional]: The shortname of the item. While both this and id are
optional, one or the other must exist for each item, or else fail with “items[index]”:
“No ID”. If both are specified, they must both reference the same item, or else fail
with “items[index]”: “Conflicting ID”. If the ID and/or shortname reference an item
that doesn’t exist, fail with “items[index]”: “Not found”.
o quantity [optional]: If the specified item is stackable, then quantity must be
present and a positive number; if the item is not stackable, quantity must either
be absent or 1. If quantity must be present and missing, zero or less, or if it must
not be present and is, fail with “items[index]”: “Invalid quantity”.
Response Fields:
• inventory: An array of inventory instances:
o id: The ID of the created instance of the item.
2017S v1.1 (2/25/2017) 3566
o itemid: The ID of the item.
o shortname: The shortname of the item.
o quantity: If the item is stackable, the quantity created; otherwise 1.
This call must be atomic—that is, it must either entirely succeed, or it must fail with no side
effects. It is not valid for some items to be created and some to not.
There can only be one inventory entry for a given stackable item. A caller is free to try to create
multiple entries for a given stackable, but the system must silently merge them into a single
entry.
The inventory array returned by this call must have the same number of elements in the same
order as the request parameter array. In the case of multiple instances of the same stackable,
the resulting actual stackable inventory instance should simply be returned multiple times in the
response.
Inventory: Update
Path: /api/v1/inventory/:id/update
Requires Authentication?: Yes
Read-only?: No
Parameters:
• id: The ID of the inventory instance.
• quantity: The new quantity. Stackable items must have a non-negative quantity, while
non-stackable items can only have quantity 0 or 1. If the quantity property does not meet
these rules, fail with “quantity”: “Invalid”.
Response Fields:
• id: The ID of the inventory instance.
• quantity: The new quantity value.
Inventory: List
Path: /api/v1/users/:userid/inventory/list
Requires Authentication?: Yes
Read-only?: Yes
Parameters:
• userid: The ID of the user.
Response Fields:
• inventory: An array of inventory instances:
o id: The ID of the created instance of the item.
o itemid: The ID of the item.
o shortname: The shortname of the item.
o quantity: If the item is stackable, the quantity of the item; otherwise 1.
2017S v1.1 (2/25/2017) 3666
API Auditing: User History
Path: /api/v1/audit/users/:id
Requires Authentication?: Yes
Read-only?: Yes
Parameters:
• id: The ID of the user to audit.
The caller must be an admin; otherwise fail with “id”: “Forbidden”.
Response Fields:
• requests: An array of objects representing every API call the specified user has ever
made to the system:
o url: The requested URL
o params: An object of all parameters passed in
o user: The ID of the authenticated user, if any
o when: The ISO-8601 date of the request
o ip: The IP address the request came from
o response: The entire body of the response
API Auditing: Inventory History
Path: /api/v1/audit/inventory/:id
Requires Authentication?: Yes
Read-only?: Yes
Parameters:
• id: The ID of the inventory item to audit.
The caller must be an admin; otherwise fail with “id”: “Forbidden”.
Response Fields:
• requests: An array of objects representing every API call that changed the state of the
specified inventory entry—including the API call that created it, any API calls that
changed its quantity and any API calls that removed it (e.g. as payment for a purchase):
o url: The requested URL
o params: An object of all parameters passed in
o user: The ID of the authenticated user, if any
o when: The ISO-8601 date of the request
o ip: The IP address the request came from
o response: The entire body of the response