Capstone-Community-Bounty

This project was designed and implemented by Kenneth Wyckoff, Sarah Turner, and John Hash for the Oregon State University Post Baccalaureate Program in Computer Science as part of the final Capstone project.

Website: https://community-bounty.azurewebsites.net

Base URL for endpoints: https://community-bounty.azurewebsites.net/api

Capstone-Community-Bounty

Table of Contents

Core Stack Overview

Deployment of Stack

Tools, External APIs, Libraries, and Auxiliary Systems

Azure

Google Cloud

Auth0

Material UI and Reactstrap

Esri

Git and GitHub

Data Model

Collection: People

Collection: Addresses

Collection: Contacts

Collection: Profiles

Collection: Solicitations

Collection: Transactions

Collection: Items

API Specification

People Routes

Check If a Person Exists

Transactions Routes

View All Transactions

Request

Response

View All Transactions For a Buyer

Request

Response

View All Transactions For a Seller

Insert a Message into a Transaction

Request

Response

Delete a Message from a Transaction

View Address By Person Sub

Request

Response

Get Addresses Within a Specified Radius

Create Default Address for a Person

Profiles Routes

Check If Profile Exists

Request

Response

View a Single Profile

Add an Item to Watchlist in Profile

Request

Response

View a Profile's Watchlist

Request

Response

Delete a Watchlist Item

Items Routes

Get All Items of a Type

Solicitations Routes

View All Solicitations

Request

Response

View All Solicitations By a Seller

Request

Response

View All Solicitations Around a Set of Coordinates

Request

Response

View All Solicitations at an Address

Add Image to Solicitation

Contact Routes (Legacy Routes)

Core Stack Overview

Our application uses a MERN stack with Typescript on the frontend. This is a three tier architecture for frontend, backend, and database using Javascript and JSON. The client-facing frontend is React Typescript with the addition of Auth0 Provider which uses React Context to manage the authentication state globally. Next there is Express framework running on our Node server which enables all the connections for our API to render rich data in the client. The server coordinates with the CosmoDB API for MongoDB via callbacks and promises to access or change data. Additionally, our server uses the Mongoose library to connect to CosmoDB and to model our document structure.

Deployment of Stack

There is a public repository that is a copy of the code with removal of some private configuration items that are required within the CI/CD deployment architecture. The publicly available repository is available here:

https://github.com/phoridFly/capstone_community_bounty

Within the repository is the following structure:

root - Within the root folder is the entry file for the server, server.js, and npm package management files for the server side of the application
server - The server folder contains subfolders of models and routes , as well as configuration for the server connection to the database. The models folder has mongoose model schemas for each collection in our database. The routes folder contains all the API routes for each respective collection. The API for our application is documented in detail in our ReadMe at the public GitHub repo mentioned above.
helpers and config - These folders each contain one file and are both used in conjunction with the Google Cloud Bucket for handling imagery.
client - In the client folder at the root, there are all the configuration files to support the client. Additional nested structure follows: 1. public - This folder contains the publicly viewable html file and metadata. Icons associated with the application such as the favico and public branding are also here. 2. src - All the source code is here. At the root level are the entry point (index.tsx) and core routing (app.tsx) of the application. Additional Typescript module declarations and the Webpack config are listed here. Further folders nested within are below.
1. header - Files to support the core navigation navbar components are here.
2. models - Typescript interfaces for API data handling are here.
3. pages - There are six subfolders here that each hold the components that are tied to individual routes within the application. Some common styling is located at the root level, along with an index.ts file to export the components to make them available across the source code.
4. services - Core interactions with our API are here arranged by database collection.

Tools, External APIs, Libraries, and Auxiliary Systems

All of our application was written in Javascript with the use of Typescript to extend Javascript in the client only. We used a myriad of external APIs and libraries for our development, and the full listing of all libraries can be found in the package.json files for both the server and the client. Azure and Google Cloud were both used for API services and data hosting. Auth0 services are in use for authorization and state storage to protect unauthorized access. The client heavily uses Material UI and Reactstrap APIs for component layouts. The core map functionality was integrated via Esri's Arcgis Javascript API. As a team, we heavily used GitHub for our VCS, CI/CD pipeline, and used issue and board tools to track progress with branches. Each of these will be discussed in detail below.

Azure

As mentioned previously, Azure hosts our app as a Linux application with associated service support. We have a resource group for Community Bounty and manage the configuration of the deployed application using their tools. Additionally, the Cosmos DB account with associated APIs is hosted within this resource group. We originally pursued the use of the B2C service for user management and access with Azure, but abandoned it due to difficulty in properly configuring all the endpoints. We also abandoned blob storage on Azure for the same reason. On a final note with Azure, semi-frequent outages of the hosting platform have also occurred.

Google Cloud

Google Cloud is used to host blob storage for client imagery management, which is primarily seller posts of items for sale and profile images. The Google Bucket is accessed via the 'uploady' library and 'multer' helpers. Google Places API and geocoding API are both in use in the address section of our application. When a user enters an address, Google Places autocomplete API is used to fetch a list of validated addresses. Once an address is selected, the Google place_id is sent to our server. Once there it is geocoded via the geocoding API. This allows map integration for user posts once they are created and tied to addresses.

Auth0

Auth0 and the Auth0 React SDK were used to provide both state management for authorization and identification of unique users based on the user sub created by Auth0. The React SDK uses React Context state management as a state provider at the root of our client entry point. This ensures only authenticated users can login. Auth0 handles all sign-up, login and logout processes/data in addition to jwt management.

Material UI and Reactstrap

Material UI and Reactstrap are both React Component libraries to assist with both visual and functional layouts of React Components. These components are in many ways the foundation of the application, and we built the props, function and state management around the core components provided by them for many views and pages. Reactstrap is used most heavily on the main navigation and cards/tabs on the homepage. Material-UI is used heavily elsewhere. The homepage (before logging in) is the exception as it is primarily made with css and elements with only a material UI button.

Esri

All map functionality on the homepage is provided by Esri ArcGIS Javascript API. A parent component to the map and left sidebar manages the layout. The props to support rendering the data are passed from parent to the siblings and the state between the sibling components is managed via the parent. The connection of rendering map data in the map component to props in the parent is something we would do differently if starting over. Integration of feature layers and customized widgets are more suitable for overall browser memory management instead of React state management and API fetches based on our exploration. However, integration of all the map functionality and geocoding functions with both Google Maps and MongoDB GeoJSON has been a great learning experience.

Git and GitHub

Git control and GitHub were integral to our team being able to work together to fix problems. We would often trade-off on features or problems to resolve them over time, and it would have been very difficult without git controls. Additionally, we used a Kanban-esque board and issue tracking with GitHub that we could link to pull requests. These tools helped our team to stay on track and realize when we needed to come together to re-evaluate an approach due to slip.

Data Model

Collection: People(#_9tsd9tukcd5f)

Property	Type	Valid Values	Description	Required?
_id	string	Arabic Numerals	Auto-generated by MongoDB / Cosmos	Yes
name	string	English letters, max length:	Full name of user.	Yes
nickname	string	English letters, Arabic numerals max length:	Name chosen by user to represent themselves on the BYF platform	Yes
person_sub	string	Letters, numbers, pipe	Auto-generated by Auth0 server	Yes
picture	string	.jpg, .png	File name of image stored in Google Bucket.	No
solicitations	array	Solicitation id numbers	This will be an array of solicitation id numbers that are associated with the user.	No
address_id	array	Address id numbers	Array of address id numbers associated with person.	No
contact_id	string	Arabic Numerals	Currently Unused	No
profile_id	string	Arabic Numerals	Currently Unused	No
transactions_id	string	Arabic Numerals	This will be an array of transaction id numbers that are associated with the user	No
seller_rating	number	Arabic Numerals	Rating from 0 to 5	No
buyer_rating	number	Arabic Numerals	Rating from 0 to 5	No

Collection: Addresses

Property	Type	Valid Values	Description	Required?
_id	GUID	Address ID numbers	Global Unique Identifier for Addresses auto generated by MongoDB	Yes
person_sub	GUID	letters, numbers, pipe	JWT sub value generated by Auth0 server	Yes
place_id	GUID	alphanumeric	Generated by Google to uniquely represent a geocoded address.	Yes
location	object	integers	GeoJASON formatted object of type "point"	Yes
address_name	string	string	User defined name of address	Yes

Collection: Contacts

Note: Contacts is a legacy collection that may be removed in a future API update.

Property	Type	Valid Values	Description	Required?
_id	string	Alphanumeric	Auto generated by MongoDB	Yes
email	string	Alphanumeric	User's email account	Yes
phone_number	int	Integer	User's phone number	No
social_id	Array	Array of valid client keys to social media	User's connections to linked social accounts	No

Collection: Profiles

Property	Type	Valid Values	Description	Required?
_id	GUID	Profile ID numbers	Global Unique Identifier for profile	Yes
person_sub	GUID	alphanumeric and pipe	Generated by Auth0 server	Yes
session_location	enum	true,false	Client provides long/lat(if true) or default_loc_buy is used (if false. Default is true	Yes
contact_method	enum	text, email, app	Preferred contact method. Default: app will be set in post	Yes
search_radius	enum	5, 10, 15, 20, 30, 40, 50, 75	Enumerations for radius ranges, determine search radius	Yes
loc_ambiguity	enum	1, 5, 10	Address offset to obfuscate location of products offered.	Yes
watchlist	Array	Item_id GUIDs	Array of item item_id for foods for which the user wants alerts.	No

Collection: Solicitations

Property	Type	Valid Values	Description	Required?
_id	GUID	Solicitations ID numbers	Global Unique Identifier for solicitations	Yes
seller_sub	GUID	alphanumeric and pipe	Sub property of JWT issued by Auth0	Yes
seller_nickname	string	alphanumeric	nickname of currently signed in user	Yes
product_name	string	letters	Only names available from authoritative list	Yes
item_id	GUID	Item ID numbers	GUID for product being offered	Yes
product_cost	number	Integers and decimal	Seller's desired cost to buyers.	Yes
cost_unit	string	Alphanumeric	User specifies units for the advertised cost.	Yes
description	String	Alphanumeric	Seller's description of product offered.	No
still_active	boolean	true or false	Whether the solicitation is still active (true) or not (false)	Yes
still_available	boolean	true or false	Whether the solicitation is still available (true) or not (false)	Yes
address_id	GUID	Address ID numbers	GUID for address for seller to indicate where product is available.	Yes
food_pic	string	.jpg or .png	User entered string for product image. Image name is prepended with solicitation_id before being stored in DB and Google Bucket.	No
compost_heap	boolean	true or false	Whether the solicitation is in "compost heap" (true) or not (false). This is permanent deactivation of solicitation.	Yes

Collection: Transactions

Property	Type	Valid Values	Description	Required?
_id	GUID	alphanumeric	Globally unique identifier for resource	Yes
buyer_sub	GUID	alphanumeric and pipe	Sub property of JWT issued by Auth0	Yes
buyer_review_verbose	string	alphanumeric	Feedback given by buyer about transaction	No
buyer_review_numeric	number	Arabic numerals	Rating from 0 to 5	No
seller_sub	GUID	alphanumeric and pipe	Sub property of JWT issued by Auth0	Yes
seller_review_verbose	string	alphanumeric	Feedback given by seller about transaction	No
seller_review_numeric	number	Arabic numerals	Rating from 0 to 5	No
solicitation_id	GUID	alphanumeric	Unique identifier for associated solicitation	Yes
message_log	array	object	Array of objects containing (person_sub: val, time_stamp: val, message: val)
person_sub is uniquely ids person writing message
time_stamp is auto generated
message is alphanumeric string entered by user	No
completed	boolean	true, false	Transaction is initially created with value of false for completed	Yes
seller_nickname	string	alphanumeric	nickname of the person selling item	Yes
buyer_nickname	string	alphanumeric	nickname of the person buying the item	Yes

Collection: Items

Property	Type	Valid Values	Description	Required?
_id	GUID	Item id	Auto generated and unique	Yes
product_name	string	Single or multi-word strings	Name of the item to be given or sold	Yes
product_type	enum	Enums only	Animal products, produce	Yes

API Specification

Routes for managing documents in the database collections are given below.

People Routes

Create Person

Allows for the creation of a new user on the platform

POST/people

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

Field	Type	Description	Required?
name	String	Users name	Yes
nickname	String	User's preferred alias on platform	Yes
picture	image	Users may upload an image or a default image will be assigned otherwise.	No
user_sub	GUID	Generated from Auth0 server	Yes

Request Body Example:

| { "name": "John Wayne", "nickName": "Duke", "picture": "default.jpg", "user_sub": "auth0|1q2w3e4r5t6y7u8i9o0p"

}

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.
Failure	409	Conflict.

Response Notes:

Database automatically generates id field.
Value for address_id begins null. It must be updated later.
Value for solicitations begins as an empty array. It may be updated later.
Value for picture is prepended with the user_sub

Success

| Status: 201 Created { "firstName": "John", "lastName": "Wayne", "nickName": "Duke", "picture": "defualt.jpg", "solicitations": [], "address_id": [], "transactions": [], "_id": "abc123", "_v": 0 }

| | --- |

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

Failure

Status: 409 Conflict{ "Error": "Account with this nickname already exists."}

Add Image to Person

Allows for posting a new photo that is linked to a user. Route also updates the person document.

POST/people/images/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID string	Sub value of JWT to id person	Yes

Request Body:

Required

Format of request body must be "form-data"

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

Field	Type	Description	Required?
NA	file	selected file	Yes

Response

Response Body:

Success: none

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	Created.
Failure	404	Not found

Response Header:

Link to the resource is returned in the response header

Note: The route prepends the user_sub to the filename of the incoming file before storing the new filename in the database and in the cloud storage.

Example: "auth0|1q2w3e4r5t6y7u8i9o0p_my-fancy-face.jpg"

View Person

Allows for viewing a single user resource.

GET/people/:people_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
people_sub	GUID string	sub value of JWT for a person	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK {"_id": {"$oid": "5f9037bf3749fd0d0cad1dc0"},"solicitations": ["5fc57a2b448f28003566e1a4"],"address_id": ["5fbc23a92f8a9f0035f25679"],"transactions_id": ["5fc57543448f28003566e1a2"],"name": "John Hash","nickname": "The BatMan","picture": "auth0|1a2s3d4f5g6h7j7j_brian.jpg","__v": 0,"profile_id": "5f903c973749fd0d0cad1dc8","person_sub": "auth0|1a2s3d4f5g6h7j7j"} | | --- |

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

View All People

Allows for viewing all people in the database.

GET/people

Request

Request Parameters:

None

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"_id": {"$oid": "5f9037bf3749fd0d0cad1dc0"},"solicitations": ["5fc57a2b448f28003566e1a4"],"address_id": ["5fbc23a92f8a9f0035f25679"],"transactions_id": ["5fc57543448f28003566e1a2"],"name": "John Hash","nickname": "The BatMan","picture": "auth0|1a2s3d4f5g6h7j7j_brian.jpg","__v": 0,"profile_id": "5f903c973749fd0d0cad1dc8","person_sub": "auth0|1a2s3d4f5g6h7j7j"},

{"_id": {"$oid": "5f9037833749fd0d0cad1dbf"},"solicitations": ["5f9490d63cd47339cccb7d27","5f973a477b69a6349c23b4c1","5fc4878eae68e70035c08c36","5fc5e268d1327215749b8d40","5fc5e3c89061c716107caac1","5fc5e4109061c716107caac2","5fc5e4849061c716107caac3"],"address_id": ["5fc4876cae68e70035c08c35","5fc58aaa448f28003566e1a5","5fc5df3dd1327215749b8d3f","5fc5e39b9061c716107caac0"],"transactions_id": ["5fc30b28cbb9f7084be1fbc8","5fc30bb456c4e908591f1f28","5fc311c86da05d08820bc64a"],"name": "Sarah Turner","nickname": "Professor_Pomegranate","buyer_rating": 0,"seller_rating": 0,"picture": "auth0|9m8n7b6v5c4x3z_IMG_2323.jpg","person_sub": "auth0|9m8n7b6v5c4x3z","__v": 0,"profile_id": "5f903cc83749fd0d0cad1dc9"}

]

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

Check If a Person Exists

Allows for a specific check of whether a person exists without returning the person document.

GET/people/check/:people_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
people_sub	GUID string	sub value of JWT for a person	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK

{"person found"}

Failure

Status: 404 Not Found{"person not found"}

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

Update Person

Updates the attributes of a user.

Note: This route is not used to add contact information, profile picture, profile information, solicitations, or transactions.

PATCH/people/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID string	sub value of JWT to uniquely id a person	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

All the attributes here are optional depending on the situation.

Field	Type	Description	Required?
name	string	User's name	No
nickname	string	Fun name for CB application. Should be unique.	No
seller_rating	integer	Value of 0 – 5	No
buyer_rating	integer	Value of 0 – 5	No

Response

Response Body:

Success: none

Failure: JSON

Response Headers:

Location header has self link to updated resource.

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not found{ "Error": "Resource not found."}

Delete Person

Removes a user and associated data from the platform.

DELETE/people/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID string	value of sub property of JWT to id a person	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Person not found."}

Transactions Routes

Create a Transaction

Allows for the creation of a new transaction on the platform.

POST/transactions

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

Field	Type	Description	Required?
buyer_sub	string	sub value from JWT	Yes
buyer_nickname	string	buyer's nickname	Yes
seller_sub	string	sub value from JWT	Yes
seller_nickname	string	seller's nickname	Yes
solicitation_id	string	unique id string for the solicitation	Yes
mess	string	used in initial message to seller from buyer	Yes

Note: the attribute completed begins as default false and is not needed in request

Request Body Example:

| { "buyer_sub": "auth0|3v4b5n6m7n6b5", "buyer_nickname": "MissesT", "seller_sub": "auth0|5g5b5g5t5b5g5t5gb", "solicitations_id": "1122eerr", "seller_sub": "auth0|4v4v4f4v4f4r4v4fr4", "seller_nickname": "Creeper", "mess": "I'd like some of those oranges, please."} | | --- |

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.

Response Notes:

Database automatically generates id field.
Value for completed can be updated later, but it is automatically initialized as "false"

Success

| Status: 201 Created { "buyer_review_verbose": "", "buyer_review_numeric": "", "seller_review_verbose": "", "seller_review_numeric": "", "solicitations_id": "1122eerr", "completed": false, "buyer_sub": "auth0|3v4b5n6m7n6b5", "buyer_nickname": "MissesT", "seller_sub": "auth0|5g5b5g5t5b5g5t5gb", "solicitations_id": "1122eerr", "seller_sub": "auth0|4v4v4f4v4f4r4v4fr4", "seller_nickname": "Creeper", "_v": 0, "_id": "abc123" "message_log": [{"buyer_sub": "auth0|3v4b5n6m7n6b5", "time_stamp": "20-10-20-15:45", "message": "I'd like some of those oranges, please."}]}

| | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Associated Collections Notes:

Calling this POST route to create a new transaction will add the newly created transaction id to the array of transactions in the associated people document.

View a Transaction

Allows for viewing a single transaction resource.

GET/transactions/:transactions_id

Request

Request Parameters:

Name	Type	Description	Required?
transactions_id	String	ID of the transaction	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK { "buyer_sub": "xyz987", "buyer_nickname": "The Dude", "buyer_review_verbose": "Apples from Sarah's house were great, but two had worms in them.", "buyer_review_numeric": "5", "seller_sub": "abc123", "seller_nickname": "Apple Gal", "seller_review_verbose": "Arrived on time.", "seller_review_numeric": "5", "solicitations_id": "mbcozn345" "id": "chopknscafemg777", "complete": true, "message_log": [{"buyer_sub": "xyz987", "time_stamp": "20-10-20-15:45", "message": "I'll be there at 4pm tomorrow"},{"seller_sub": "abc123", "time_stamp": "20-10-20-16:16", "message": "Great. See you then."},{"buyer_sub": "xyz987", "time_stamp": "21-10-20-16:01", "message": "Outside picking up the apples now."}]} | | --- |

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

View All Transactions

Allows for viewing all transactions in the database.

GET/transactions

Request

Request Parameters:

None

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{ "buyer_sub": "xyz987", "buyer_nickname": "The Dude", "buyer_review_verbose": "Apples from Sarah's house were great, but two had worms in them.", "buyer_review_numeric": "5", "seller_sub": "abc123", "seller_nickname": "Apple Gal", "seller_review_verbose": "Arrived on time.", "seller_review_numeric": "5", "solicitations_id": "mbcozn345" "id": "chopknscafemg777", "complete": true, "message_log": [{"buyer_sub": "xyz987", "time_stamp": "20-10-20-15:45", "message": "I'll be there at 4pm tomorrow"},{"seller_sub": "abc123", "time_stamp": "20-10-20-16:16", "message": "Great. See you then."},{"buyer_sub": "xyz987", "time_stamp": "21-10-20-16:01", "message": "Outside picking up the apples now."}]}, { "buyer_review_verbose": "", "buyer_review_numeric": "", "seller_review_verbose": "", "seller_review_numeric": "", "solicitations_id": "1122eerr", "completed": false, "buyer_sub": "auth0|3v4b5n6m7n6b5", "buyer_nickname": "MissesT", "seller_sub": "auth0|5g5b5g5t5b5g5t5gb", "solicitations_id": "1122eerr", "seller_sub": "auth0|4v4v4f4v4f4r4v4fr4", "seller_nickname": "Creeper", "_v": 0, "_id": "abc123" "message_log": [{"buyer_sub": "auth0|3v4b5n6m7n6b5", "time_stamp": "20-10-20-15:45", "message": "I'd like some of those oranges, please."}]}

]

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

View All Transactions For a Buyer

Allows for viewing all transactions by a specific buyer.

GET/transactions/buyer/:buyer_sub

Request

Request Parameters:

Name	Type	Description	Required?
buyer_sub	String	sub value for the buyer	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK{"food_pic": "5fc5e268d1327215749b8d40_currants-3538617_1920.jpg","description": "delicious red currants available fresh","cost_unit": "pound ","product_cost": 1,"product_name": "Red Currants","_id": "5fc5eac19061c716107caacb","completed": false,"seller_sub": "auth0|noneyourbusiness2","buyer_sub": "auth0|noneyourbusiness","buyer_nickname": "Farmer_Frank","solicitation_id": "5fc5e268d1327215749b8d40","message_log": [{"_id": "5fc5eac19061c716107caacc","buyer_sub": "auth0|noneyourbusiness","message": "I love currants!","time_stamp": "2020-12-01T07:03:29.787Z"}]}

| | --- |

Failure

| Status: 404 Not Found[{"error": "You have no buyer transactions.","completed": true}] | | --- |

Note that completed will return as true here for internal purposes.

View All Transactions For a Seller

Allows for viewing all transactions by a specific buyer.

GET/transactions/seller/:seller_sub

Request

Request Parameters:

Name	Type	Description	Required?
seller_sub	String	sub value on the JWT for the seller	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| | --- |

Failure

| Status: 404 Not Found[{"error": "You have no seller transactions.","completed": true}] | | --- |

Note that completed will return as true here for internal purposes.

Update a Transaction

Allows for updating properties of the transaction exclusive of the message log.

PATCH/transactions/:transactions_id

Request

Request Parameters:

Name	Type	Description	Required?
transactions_id	String	ID of the transaction	Yes

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

All the attributes here are optional depending on the situation and whether the buyer or seller is leaving reviews.

Field	Type	Description	Required?
completed	boolean	true or false. Initialized as false, updated to true when transaction is completed	No
buyer_review_verbose	string	Buyer's review of the seller	No
seller_review_verbose	string	Seller's review of the buyer	No
seller_review_numeric	integer	Value of 0 – 5	No
buyer_review_numeric	integer	Value of 0 – 5	No

Response

Response Body:

Success: none

Failure: JSON

Response Headers:

Location header has self link to updated resource

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Status: 204 No Content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No transaction with this id exists."}

Insert a Message into a Transaction

Allows for adding a message to the the message log sub document in a transactions document

PUT/transaction/:transactions_id/messages

Request

Request Parameters:

Name	Type	Description	Required?
transactions_id	String	ID of the transaction	Yes

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

All the attributes here are required. The time stamp field in a message is generated by the server.

Field	Type	Description	Required?
message	string	Text that person wishes to add to their message	Yes
peson_sub	string	sub value in JWT for identifying a person	Yes

Response

Response Body:

Success: JSON

Failure: JSON

Response Headers:

None altered

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Status: 201 Created{ "buyer_id": "xyz987", "buyer_review_verbose": "", "buyer_review_numeric": "", "seller_id": "abc123", "seller_review_verbose": "", "seller_review_numeric": "", "solicitations_id": "mbcozn345" "id": "chopknscafemg777", "complete": true, "message_log": [{"buyer_sub": "xyz987", "time_stamp": "20-10-20-15:45", "message": "I'll be there at 4pm tomorrow"},{"seller_sub": "abc123", "time_stamp": "20-10-20-16:16", "message": "Great. See you then."},{"buyer_sub": "xyz987", "time_stamp": "21-10-20-16:01", "message": "Outside picking up the apples now."}]}

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "Transaction not found."}

Delete a Message from a Transaction

Removes a message from a transaction document.

DELETE/transaction/:transactions_id/messages/:messages_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
transactions_id	GUID	Identifies a transaction uniquely	Yes
messages_id	GUID	Identifies a message uniquely	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Resource not found."}

Delete Transaction

Removes a transaction and associated data from the platform.

DELETE/transaction/:transaction_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
transactions_id	GUID	Identifies a transaction uniquely	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Transaction not found."}

Addresses Routes

Create an Address

Allows for the creation of a new address on the platform

POST/address

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

Property	Type	Description	Required?
place_id	GUID	Generated by Google Geocoder	Yes
person_sub	GUID	sub value of JWT	Yes
address_name	string	User defined name of address	Yes

Request Body Example

{ "person_sub": "big345" "place_id": "4h5h6j77j8jfff", "address_name": "Home"}

Note: Formatted address_string and location coordinates are produced by Google Geocoding service.

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.
Failure	409	Conflict.

Response Notes:

Database automatically generates id field.
Formatted address_string and location coordinates are produced by Google Geocoding API. It requires the client to validate and get geocode before the post request.

Success

| Status: 201 Created { "_id": "bibbidyboo", "person_sub": "big345" "place_id": "4h5h6j77j8jfff", "address_string": "111 Orange Street, South Park, CO, USA" "address_name": "Home""location": {"type": "Point","coordinates": [-76.51260839999999,43.449584]} } | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 409 Conflict{ "Error": "User address name already defined"}

View an Address

Allows for viewing a single address in the database by id.

GET/address/:address_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
address_id	GUID	Address identifier	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK { "_id": "bibbidyboo", "person_sub": "big345" "place_id": "4h5h6j77j8jfff", "address_string": "111 Orange Street, South Park, CO, USA" "address_name": "Home", "default_address": "true","location": {"type": "Point","coordinates": [-76.51260839999999,43.449584]} } | | --- |

Failure

Status: 404 Not Found{ "Error": "Not Found"}

View All Addresses

Access a list of all addresses in the database.

GET/address

Request

Request Parameters:

None

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"location": {"type": "Point","coordinates": [-117.2515136,34.0571106]},"default_address": true,"_id": "5fb46dfb1e80620035b98111","person_sub": "auth0|5fa2f0bbb472680076ec9f50","place_id": "ChIJWfpelZur3IARzX5O_p38Dlk","address_string": "25339 Lane St, Loma Linda, CA 92354, USA","address_name": "Loma Linda Dwight's Beet Farm","__v": 0},{"location": {"type": "Point","coordinates": [-117.2398929,34.0533236]},"default_address": false,"_id": "5fb46e1e1e80620035b98112","person_sub": "auth0|5fa2f0bbb472680076ec9f50","place_id": "ChIJx4GgX7yr3IARxgai4yrSldw","address_string": "11035 Ragsdale Rd, Loma Linda, CA 92354, USA","address_name": "Loma Linda Pomegranate Ranch","__v": 0}]

| | --- |

Failure

Status: 404 Not Found{ "Error": "Not Found"}

View Address By Person Sub

Allows for viewing the addresses associated with a person in the database.

GET/address/person/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Sub derived from JWT that uniquely identifies a person	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Failure

Status: 404 Not Found{ "Error": "Not Found"}

Get Addresses Within a Specified Radius

Returns addresses within the specified radius of the specified coordinates.

PUT/address/radius

Request

Request Parameters:

None

Request Body:

Required

Name	Type	Description	Required?
coordinates	array	Decimal longitude and latitude	Yes
radius	integer	Radius in number of miles	Yes

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK {"location": {"type": "Point","coordinates": [-117.2398929,34.0533236]},"default_address": false,"_id": "5fb46e1e1e80620035b98112","person_sub": "auth0|5fa2f0bbb472680076ec9f50","place_id": "ChIJx4GgX7yr3IARxgai4yrSldw","address_string": "11035 Ragsdale Rd, Loma Linda, CA 92354, USA","address_name": "Loma Linda Pomegranate Ranch","__v": 0} | | --- |

Failure

Status: 404 Not Found{ "Addresses Not Found"}

Delete Address

Remove an address from the database.

DELETE/address/:address_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
address_id	GUID	Identifies an address uniquely	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Transaction not found."}

Create Default Address for a Person

Allows for changing the default address for a person.

PATCH/address/default/:person_sub/:address_name

Note: On creation of an address for a user, the first address is the default address. This route allows any user address to be designated the default.

Request

Request Parameters:

Name	Type	Description	Required?
person_sub	GUID string	sub value of JWT	Yes
address_name	string	The user given name for their address	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: none

Failure: JSON

Response Headers:

Location header has self link to updated resource

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Status: 204 No Content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No person with this id exists."}

Status: 404 Not Found{ "Error": "No address with this name exists."}

Profiles Routes

Create Profile

Allows for the creation of user profile on the platform

POST/profile

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Notes:

A post only requires a person_sub. Other attributes will be set to a default value or left blank and updated as needed.

Request Attributes

Property	Type	Valid Values	Description	Required?
person_sub	GUID	Person ID number	GUID for person, these are their profile	Yes

Request Body Example

| { "person_sub": "auth0|big345"} | | --- |

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.
Failure	409	Conflict.

Response Notes:

Database automatically generates id field.

Success

| Status: 201 Created{ "_id": "4g5h6j7", "person_sub": "auth0|big345", "session_location": "true", "contact_method": "app", "default_loc_buy": :[] "search_radius": "30", "loc_ambiguity": "5" "Watchlist":[] } | | --- | | |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 409 Conflict{ "Error": "User profile already defined"}

Check If Profile Exists

Returns a message that profile exists if found.

GET/profile/:profile_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
profile_sub	GUID	Person identifier based on sub of JWT	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK { "found" } | | --- |

Failure

Status: 404 Not Found{ "Profile not found"}

Failure

Status: 401 Unauthorized{ "No authorization token found"}

View a Single Profile

Returns a message that profile exists if found.

GET/profile/person/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Person identifier based on sub of JWT	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK { "_id": "4g5h6j7", "person_sub": "auth0|big345", "session_location": "true", "contact_method": "app", "default_loc_buy": :[] "search_radius": "30", "loc_ambiguity": "5" "Watchlist":[] } | | --- |

Failure

Status: 404 Not Found{ "Profile not found"}

Failure

Status: 401 Unauthorized{ "No authorization token found"}

View All Profiles

Get all profiles in database

GET/profile

Request

Request Parameters:

None

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"contact_method": "app","search_radius": "30","loc_ambiguity": "5","session_location": "true","watchlist": ["5f98bbfb9e4d782509a824ff","5f98bbe69e4d782509a82478","5f98bbfa9e4d782509a824f8"],"_id": "5f903c973749fd0d0cad1dc8","default_loc_buy": [],"person_sub": "auth0|nope","__v": 0},{"contact_method": "app","search_radius": "30","loc_ambiguity": "5","session_location": "true","watchlist": ["5f98bbe99e4d782509a8248c","5f98bbe99e4d782509a8248c","5f98bbdf9e4d782509a82459","5f98bbe19e4d782509a8245b","5f98bbfc9e4d782509a82506","5f98bc069e4d782509a82543"],"_id": "5f903cc83749fd0d0cad1dc9","person_sub": "auth0|backup","__v": 0},{"contact_method": "app","search_radius": "30","loc_ambiguity": "5","session_location": "true","watchlist": [],"_id": "5fb55cfc18e24f0f04cd5526","person_sub": "auth0|lookaway","__v": 0},] | | --- |

Failure

Status: 404 Not Found{ "Profile not found"}

Failure

Status: 401 Unauthorized{ "No authorization token found"}

Update Profile

Legacy Route

Updates profile attributes other than the watchlist, which has a different PUT route.

PATCH/profile/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Person identifier in JWT	Yes

Request Body:

Required

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Legacy Route: Attribute update may be reimplemented later and some have been offloaded to in application options.

Success

Status: 204 OK{"n": 1,"nModified": 1,"ok": 1}

Failure

Status: 404 Not Found{ "Error": "Not Found"}

Add an Item to Watchlist in Profile

Allows added an item to a user's watchlist

PUT/profile/:person_sub/:product_name

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Person identifier in JWT	Yes
product_name	string	string name of product wished to be added	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204

Success

Status: 204 ["_id": "5f98bbe69e4d782509a82478","product_name": "Blood Orange","product_type": "produce","__v": 0]

Failure

Status: 404 Not Found{ "Profile not found"}

View a Profile's Watchlist

Returns a watchlist array of item ids.

GET/profile/watchlist/:person_sub

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Person identifier based on sub of JWT	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK

[{"_id": "5f98bbe69e4d782509a82478","product_name": "Blood Orange","product_type": "produce","__v": 0},{"_id": "5f98bbfa9e4d782509a824f8","product_name": "Kiwifruit","product_type": "produce","__v": 0},{"_id": "5f98bbfb9e4d782509a824ff","product_name": "Lemon","product_type": "produce","__v": 0}]

| | --- |

Failure

Status: 404 Not Found{ "Items not found"}

Failure

Status: 401 Unauthorized{ "No authorization token found"}

Delete a Watchlist Item

Remove an item from a user's watchlist.

DELETE/profile/watchlist/:person_sub/:item_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
person_sub	GUID	Person identifier in JWT	Yes
item_id	GUID	id of item to remove

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Transaction not found."}

Delete Profile

Remove a profile from database

DELETE/profile/:profile_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
profile_id	GUID	unique id for profile document	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Conflict{ "Error": "Profile not found."}

Items Routes

Create Item

This is not a method exposed as a route in Express publicly. Items will be directly loaded into MongoDB interface or be a non-accessible route for clients.

POST/items/notPublic

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

Property	Type	Valid Values	Description	Required?
_id	GUID	Item id	Auto generated and unique	Y
product_name	string	Single or multi-word strings	Name of the item to be given or sold	Y
product_type	enum	Enums only	animal products, produce	Y

Request Body Example

{ "product_name": "onion", "product_type": "produce" }

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.
Failure	409	Conflict.

Response Notes:

Database automatically generates id field.
The self attribute is not stored in the database and represents a live link to the newly created REST resource.

Success

| Status: 201 Created{ "product_name": "onion", "product_type": "produce" } | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

View Single Item

Get a single item from the database by id

GET/items/:item_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
item_id	GUID	Item identifier	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK { "_id": "pp7", "product_name": "onion", "product_type": "produce" } | | --- |

Failure

Status: 404 Not Found{ "Error": "Not Found"}

View All Items

Returns array off all items in database

GET/items

Note that pagination is not yet implemented and list can be cumbersome

Request

Request Parameters:

None

Request Body:

None

Authorization:

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK[{"_id": "5f97a5f9192b772360610035","product_name": "Dragonfruit","product_type": "produce","__v": 0},{"_id": "5f98bbdf9e4d782509a82459","product_name": "Acorn Squash","product_type": "produce","__v": 0},{"_id": "5f98bbe19e4d782509a8245a","product_name": "Almonds","product_type": "produce","__v": 0}] | | --- |

Failure

Status: 404 Not Found{ "Error": "Not Found"}

Get All Items of a Type

Returns array of products of type specified

GET/items/type/:product_type

Request

Request Parameters:

Name	Type	Description	Required?
product_type	enum	'produce' or 'animal product' or only options	Yes

Request Notes:

Only these two enums are supported

Request Body:

None

Authorization:

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK[{"_id": "5f98bc109e4d782509a82580","product_name": "Eggs","product_type": "animal product","__v": 0},{"_id": "5f98bc109e4d782509a82581","product_name": "Honey","product_type": "animal product","__v": 0}] | | --- |

Failure

Status: 404 Not Found{ "Error": "Not Found"}

Delete Item

This is not a method exposed as a public route. Items will be deleted directly from MongoDB interface or be a non-accessible route for clients.

Remove a profile from database

DELETE/item/notPublic/:item_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
item_id	GUID	unique id for item document	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "Item not found."}

Solicitations Routes

Create Solicitation

Allows for the creation of a new Solicitation

POST/solicitations

Request

Request Parameters:

None

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

Field	Type	Description	Required?
product_name	String	Name of the product being offered	Yes
product_cost	String	Cost for purchase	Yes
cost_unit	String	Units product is sold in	Yes
description	String	Description of product available	Yes
still_active	Boolean	Indicator of whether the product is still being offered	Yes
still_available	Boolean	Indicator of whether product is immediately available	Yes
address_id	GUID	Address where product is being offered	Yes
compost_heap	Boolean	Indicates whether it is permanently removed	Yes
seller_sub	GUID	Sub property of jwt	Yes

Note that product image food_pic is not added in this route.

Request Body Example

{ "product_name": "carrot", "product_cost": "1", "cost_unit": "bushel", "description": "standard orange root fruit", "still_active" "true", "still_available": "true", "compost_heap": "false", "seller_sub": "123456abcdef", "product_id": "fed456abc123", "address_id": "edc624afb351"}

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	201	Created.
Failure	401	Unauthorized.
Failure	409	Conflict.

Response Notes:

Database automatically generates id field.
The self attribute is not stored in the database and represents a live link to the newly created REST resource.

Success

| Status: 201 Created { "product_name": "carrot", "product_cost": "1", "cost_unit": "bushel", "description": "standard orange root fruit", "still_active" "true", "still_available": "true", "compost_heap": "false", "seller_sub": "123456abcdef", "product_id": "fed456abc123", "address_id": "edc624afb351"} | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 409 Conflict{ "Error": "Solicitation already exists."}

View a Solicitation

Allows for viewing a single solicitation resource.

GET/solicitations/:solicitations_id

Request

Request Parameters:

Name	Type	Description	Required?
solicitations_id	String	ID of the solicitation	Yes

Request Body:

None

Authorization:

Required

Header: Accept

Required

Value of the "Accept" header must be "application/json"

Request Attributes

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK {"_id": "5fc9387ac5f0c900350e10ec","product_name": "Kale","product_cost": 2.25,"cost_unit": "bunch","description": "Fresh and packed with vitamins.","still_active": true,"still_available": true,"compost_heap": false,"seller_sub": "auth0|dontlook1111","address_id": "5fc9383fc5f0c900350e10eb","__v": 0,"food_pic": "5fc9387ac5f0c900350e10ec_kale.jpg"} | | --- |

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

View All Solicitations

Allows for viewing all solicitations in the database.

GET/solicitations

Request

Request Parameters:

None

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"_id": "5fc5e268d1327215749b8d40","product_name": "Red Currants","product_cost": 1,"cost_unit": "pound ","description": "delicious red currants available fresh","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|no4no4no4no","address_id": "5fc5df3dd1327215749b8d3f","__v": 0,"food_pic": "5fc5e268d1327215749b8d40_currants-3538617_1920.jpg"},{"_id": "5fc5e3c89061c716107caac1","product_name": "Butternut Squash","product_cost": 0,"cost_unit": "","description": "Free butternut squash grown in our garden","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|cantseeme123","address_id": "5fc5e39b9061c716107caac0","__v": 0,"food_pic": "5fc5e3c89061c716107caac1_pumpkin-2802114_1920.jpg"}] | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

View All Solicitations By a Seller

Allows for viewing all solicitations in the database looking them up by seller_sub

GET/solicitations/:seller_sub

Request

Request Parameters:

Name	Type	Description	Required?
seller_sub	GUID	Sub property of JSON web token	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No solicitations found."}

View All Solicitations Around a Set of Coordinates

Allows for viewing all solicitations in the database within a given radius of a set of coordinates.

GET/solicitations/radius/:centerLong/:centerLat/:rad

Request

Request Parameters:

Required

Name	Type	Description	Required?
centerLong	number	longitude of point	Yes
centerLat	number	latitude of point	Yes
rad	integer	radius in number of miles	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"_id": "5fc5e268d1327215749b8d40","product_name": "Red Currants","product_cost": 1,"cost_unit": "pound ","description": "delicious red currants available fresh","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|no4no4no4no","cooridates": "[-122, 44]","__v": 0,"food_pic": "5fc5e268d1327215749b8d40_currants-3538617_1920.jpg"},{"_id": "5fc5e3c89061c716107caac1","product_name": "Butternut Squash","product_cost": 0,"cost_unit": "","description": "Free butternut squash grown in our garden","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|cantseeme123","coordinates": "[-122, 44]","__v": 0,"food_pic": "5fc5e3c89061c716107caac1_pumpkin-2802114_1920.jpg"}] | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "No resource with this id exists."}

View All Solicitations at an Address

Allows for viewing all solicitations in the database associated with an address id.

GET/solicitations/address/:address_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
address_id	GUID	id of address auto generated by MongoDB	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: "application/json"

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	200	OK.
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

| Status: 200 OK [{"_id": "5fc5e268d1327215749b8d40","product_name": "Red Currants","product_cost": 1,"cost_unit": "pound ","description": "delicious red currants available fresh","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|no4no4no4no","cooridates": "[-122, 44]","__v": 0,"food_pic": "5fc5e268d1327215749b8d40_currants-3538617_1920.jpg"},{"_id": "5fc5e3c89061c716107caac1","product_name": "Butternut Squash","product_cost": 0,"cost_unit": "","description": "Free butternut squash grown in our garden","still_active": true,"still_available": true,"compost_heap": false,"seller_nickname": "Professor_Pomegranate","seller_sub": "auth0|cantseeme123","coordinates": "[-122, 44]","__v": 0,"food_pic": "5fc5e3c89061c716107caac1_pumpkin-2802114_1920.jpg"}] | | --- |

Failure

Status: 401 Unauthorized{ "Error": "No Authorization Token Found."}

Failure

Status: 404 Not Found{ "Error": "Solicitations not found."}

Update Solicitation

Allows for updating properties of a solicitation. This is not used for a photo upload.

PATCH/solicitations/:solicitations_id

Request

Request Parameters:

Name	Type	Description	Required?
solicitations_id	String	ID of the solicitation	Yes

Request Body:

Required

Format of request body must be JSON

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

All the attributes here are optional depending on the situation.

Field	Type	Description	Required?
product_name	String	Name of the product being offered	No
product_cost	String	Cost for purchase	No
cost_unit	String	Units product is sold in	No
description	String	Description of product available	No
still_active	Boolean	Indicator of whether the product is still being offered	No
still_available	Boolean	Indicator of whether product is immediately available	No
address_id	GUID	Address where product is being offered	No
compost_heap	Boolean	Indicates whether it is permanently removed	No
seller_sub	GUID	Sub property of jwt	No

Response

Response Body:

Success: none

Failure: JSON

Response Headers:

None altered

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content
Failure	404	Resource not found.
Failure	401	Unauthorized.

Success

Status: 204 No Content

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

Failure

Status: 404 Not Found{ "Error": "Solicitation not found."}

Add Image to Solicitation

Allows for posting a new photo that is linked to food posting solicitation

POST/solicitations/images/:solicitation_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
solicitation_id	GUID string	id of database document	Yes

Request Body:

Required

Format of request body must be "form-data"

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

Field	Type	Description	Required?
NA	file	selected file	Yes

Response

Response Body:

Success: none

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	Created.
Failure	404	Not found

Response Header:

Link to the resource is returned in the response header

Note: The route prepends the solicitation_id to the filename of the incoming file before storing the new filename in the database and in the cloud storage.

Example: "44jhfught7ght7gh_my-pomegranate.jpg"

Delete Solicitation

Removes a solicitation and associated data from the platform.

DELETE/solicitations/:solicitations_id

Request

Request Parameters:

Required

Name	Type	Description	Required?
solicitations_id	GUID	Identifies a solicitation uniquely	Yes

Request Body:

None

Authorization:

Required

Header: Accept:

Required

Value of the "Accept" header must be "application/json"

Request Attributes:

None

Response

Response Body:

Success: None

Failure: "application/json"

Response Statuses:

Outcome	Status Code	Notes
Success	204	No content.
Failure	401	Unauthorized.
Failure	404	Not found.

Response Notes:

Success

Status: 204 No content

Failure

Status: 401 Unauthorized{ "Error": "Invalid credentials."}

Failure

Status: 404 Conflict{ "Error": "Solicitation not found."}

Contact Routes (Legacy Routes)

These routes were used early on in the development of the project but do not have a function at this time. They are kept here as stubs to acknowledge they exist and could be useful in the future.

Create Contact

Allows for the creation of a new Contact

POST/contacts

View a Contact

Allows for viewing a single contact resource.

GET/contacts/:contacts_id

View All Contacts

Allows for viewing all transactions in the database.

GET/contacts

Update Contact

Allows for updating properties of a contact.

PATCH/contacts/:contacts_id

Delete Contact

Removes a transaction and associated data from the platform.

DELETE/contacts/:contacts_id

phoridfly / capstone_community_bounty Goto Github PK