Inpassing Web Service

Data model

See inpassing/models.py for all the details.

Org

Orgs have parking spaces and give out passes to users. Each org has a set of states and some amount of parking spaces.

User

Users can moderate an org or participate in an org.

Pass

Passes are defined by a state and a spot number. The state could be 'A', 'B' for A-B parking or 'M', 'T', 'W', etc for schedules that work on a weekly basis. Passes don’t exist until they are claimed by a user and verified by an org. Passes store a requested state and spot number, but must be verified by an org at which point they may assign a different state and spot number.

DayState

Right now it’s basically a string that users of the service will recognize, IE 'A' or 'B' or 'Monday' or 'Tuesday', etc. It is referenced by its unique ID.

API

Endpoint	Description	Authentication	Parameters / Form
POST /user/#	Creates a new user returning its ID in a json object	None	Form data: first_name, last_name, email, password
POST /user/auth	Authenticates the user and returns a "Bearer" token.	None	Form data: email, password
GET /me	Returns JSON object of user information based on login token. Includes id, first_name, last_name, email, orgs that this user participates in, orgs that this user moderates in, and all types of passes: pending, owned, and lent.	Authorization: Bearer <token>	None
GET /me/passes	Returns only the pass information from GET /me.	Authorization: Bearer <token>	None
POST /org/<org_id>/pass	Requests a pass on behalf of the current user. Returns the new pass ID. It will need to be verified by the org before it can be used.	Authorization: Bearer <token>	Form data: state_id, spot_num.
GET /org/<org_id>	Returns a JSON object describing the org. If the current user (given an auth token) is not a participant or mod of the org, only the name is provided. Otherwise the greeting and rules are provided as well.	Optional: Authorization: Bearer <token>	None
GET /org/search	Searches organization by name, returning its ID and full name. q parameter is the search string.	None	URL: q
POST /pass/borrow	Requests a pass on behalf of the user on the given date or date range. Dates should be given in the format YYYY-MM-DD (eg 2017-03-31)	Authorization: Bearer <token>	Form data: date or start_date and end_date
POST /pass/<pass_id>/lend	Lends a pass on the given date or date range. See above for the date format. Users can only lend passes they have the rights to at that moment.	Authorization: Bearer <token>	Form data: date or start_date and end_date

Implementing borrow and lend

There are a few things we want our system to accomplish:

1. Requests for a pass are first-come-first-serve.

2. One person shouldn’t be able to request a pass for every day, putting them in the front of every queue for the foreseeable future.

3. People must be able to have multiple requests for a pass open at a time.

   1. This will enable requests for passes on specific dates, specific blocks of dates, indefinitely (until a pass comes up), etc.

4. People should be able to request a pass the day of and receive it immediately, if possible. This is a bit of an issue if everyone joins the indefinite queue.

Ideas

1. Have a lender (producer) and borrower (consumer) queue for each day and another set of queues for indefinite users.

2. Attach some unique (preferably ordered) token to each user and each request they make.

3. Match up producers with borrowers at some point (not necessary immediately).

4. When a borrower uses a pass, all of their future requests are moved to the back of their respective queue. This could be implemented by identifying the request with the token, then updating the token and re-adding the user’s request at the back of the queue.

   1. This would only happen when the lender "consumes" the pass. We want to wait as long as possible to "lock-in" each pass so that we allow for more people to join the queue and possibly get a pass if someone in front of them is moved back.

   2. The indefinite list will not automatically be considered for queues that have already been locked-in.