Requirements - PadraigGillen/trading-ports GitHub Wiki


We are to develop a REST API that will create and modify boats and subsequently slips for boats to dock at. This is to mimic a collection of trading ports. Each user will have their own trading port, which will have their own number of slips for boats to dock in. In order for a person to have access to their own trading port, they will be required to log in through an Oauth service.


The Boat objects will have the following properties:

id - This should be automatically generated by your API and should probably be a string
name - The name of the boat, a string
type - The type of boat, power boat, sailboat, catamaran etc. a string
length - The length of the boat
at_sea - A boolean indicating if the boat is at sea or not

Each boat will be managed purely by the needs of the back end server. The number of boats that well exist within the database will be equal to the equation

num_boats = int(sum(user_1_slips[] + user_2_slips[] + ... user_n_slips[]) * 0.8) 

If the current number of boats is lower than the 80% potential occupancy rate, based on the number of slips, then a boat will be created once every 2 minutes until the rate is met. When a boat is created its type will be picked from a sequential order through a list of boat types.

When the number of slips no longer reflect an 80% potential occupancy rate, the boats that are to be destroyed to return to the correct rate will be chosen randomly.

Each boat will be able to travel to any users port and dock in any users slip. To travel from one port to another port, it will take the boat 2 minutes. Once The boat arrives a port, it will take the boat 1 minute to dock in a slip, so long as there is an unoccupied slip available at the end of the waiting period. While docked at a slip, the boats will decide to stay there for anywhere between 1 to 10 minutes. To undock from a slip, it will take the boat one minute to return to sea. This means that the shortest time possible for a boat to return to the sea is 2 minutes, 1 for waiting at the slip and the other for preparing to leave the slip.

If two boats attempt to dock in the same slip, the boat who's wait time completes first will take priority and dock at the slip. The boat which has the longest wait time will then re-evaluate what action it wishes to take after it's wait time to attempt to dock has completed.

The actions that the boats while at sea are random. While at sea, they have the following options

  • Travel to a random port.
  • Dock at a port.
  • wait outside of the current port for 1 to 10 minutes.


The Slip objects will have the following format:

id - A string generated by your API
number - The the slip number, essentially the human understandable identifier
current_boat - The id of the current boat, null if empty
arrival_date - A string indicating the date the boat arrived in the slip
departure_history - A list of the dates that previous boats departed the slip

A slip can only be created or destroyed by a user. If there are no


All ship and slip data will be stored in a database that can be accessed and manipulated via REST API requests. To access the database, it will be required for an individual to log into their own personal session. In this session, they will have access to increasing or decreasing the number of slips that they own. The number of slips they own cannot be below 1.

When a user requests to create an account the account begins with a single slip.



This project is based on an assignment provided by Justin Wolford at Oregon State University. The assignment specification can be found here.