Skip to content

README.md

Latest commit

 

History

History
2514 lines (2104 loc) · 49.2 KB

README.md

File metadata and controls

2514 lines (2104 loc) · 49.2 KB
Raw

FindNUS Backend API

API documentation for FindNUS backend services. Handles the retrieval, processing and management of Lost Items found in NUS. Comes with additional spicy features like NLP and elasticsearch.

Table of Contents

## Servers
URL Description
https://findnus.herokuapp.com Production cluster that is hosting the backend services for FindNUS
https://uat-findnus.herokuapp.com User-Acceptance Testing cluster environment for testing

Paths

GET /debug/ping

Returns a Hello World equivalent message. Shows that the backend connection works.

Responses

▶ 200 - A hello world message.
Headers

No headers specified

text/plain
Name Type Description Accepted values
Response string Any
Example
message: Hi there, you have reached FindNUS!

GET /debug/checkAuth

Check with backend if the Firebase token is valid.

Headers

▷ Authorization

Firebase ID token of user

Name Type In Description Accepted values
Authorization (required) string header Firebase ID token of user Any
Example
"Authorization: my-firebase-idToken"

Responses

▶ 200 - Id token is valid
Headers

No headers specified

▶ 401 - Id token is invalid
Headers

No headers specified

GET /debug/getDemoItem

Get a demo item for Milestone 1.

Query parameters

▷ name

Name of the demoset item to be retrieved

Name Type In Description Accepted values
name (required) string query Name of the demoset item to be retrieved Any

Responses

▶ 200 - Get request is valid, item is found
Headers

No headers specified

application/json
Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Name (required) string Name of lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_url string Item's accompanying image link Any
User_id string UserID associated to this item. Only applicable for Lookout Items. Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag IS REQUIRED.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_url": "https://imgur.com/gallery/RaHyECD",
  "User_id": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}
▶ 404 - Get request is valid, item not found
Headers

No headers specified

text/plain
Name Type Description Accepted values
Response string Any
Example
Nothing Found!

POST /item

Add new Lost item to be put on Lookout on the database.

Headers

▷ Authorization

Firebase ID token of user

Name Type In Description Accepted values
Authorization (required) string header Firebase ID token of user Any
Example
"Authorization: my-firebase-idToken"

Request body

application/json
Name Type Description Accepted values
User_id string Unique User_id generated by firebase to associate a user to a Lookout item. Any
Name (required) string Name of new lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_base64 string Accompanying image of new Lost/Found item, if applicable Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag should only exist for Lost items.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "User_id": "string",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_base64": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}

Responses

▶ 200 - Item registered into database
Headers

No headers specified

▶ 400 - Rejected new item into database
Headers

No headers specified

▶ 401 - Firebase credentials not invalid
Headers

No headers specified

PATCH /item

Update details of an item on the database.

Headers

▷ Authorization

Firebase ID token of user

Name Type In Description Accepted values
Authorization (required) string header Firebase ID token of user Any
Example
"Authorization: my-firebase-idToken"

Query parameters

▷ Id

MongoDB ID of the Item

Name Type In Description Accepted values
Id (required) string query MongoDB ID of the Item Any
Example
"Id=629cc52563533a84f60c4c68"
▷ User_id

FindNUS User Id (for lost item lookout requests). Include this to remove from Lost (Lookout) Items collection.

Name Type In Description Accepted values
User_id (required) string query

FindNUS User Id (for lost item lookout requests). Include this to remove from Lost (Lookout) Items collection.

 Any
Example
"User_id=196afas7"

Request body

application/json
Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
User_id string Unique User_id generated by firebase to associate a user to a Lookout item. Any
Name string Name of new lost/found item Any
Date string Date-time where item is lost/found Any
Location string Where the item was found Any
Category string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_base64 string Updated image of Lost/Found item, if applicable Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag should only exist for Lost items.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "User_id": "string",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_base64": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}

Responses

▶ 200 - OK
Headers

No headers specified

▶ 401 - Firebase credentials not invalid
Headers

No headers specified

GET /item

Get a particular item's full details

Query parameters

▷ Id

Item Id reference. Case sensitive.

Name Type In Description Accepted values
Id (required) string query Item Id reference. Case sensitive. Any
▷ User_id

User_id filter to search for this Id in the LOST collection. Case sensitive.

Name Type In Description Accepted values
User_id string query User_id filter to search for this Id in the LOST collection. Case sensitive. Any

Responses

▶ 200 - A Lost Item's details
Headers

No headers specified

application/json
Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Name (required) string Name of lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_url string Item's accompanying image link Any
User_id string UserID associated to this item. Only applicable for Lookout Items. Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag IS REQUIRED.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_url": "https://imgur.com/gallery/RaHyECD",
  "User_id": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}
▶ 404 - Item not found
Headers

No headers specified

▶ 500 - Internal server error. Likely to be a message queue fault.
Headers

No headers specified

DELETE /item

Remove an item listing on the database.

Headers

▷ Authorization

Firebase ID token of user

Name Type In Description Accepted values
Authorization (required) string header Firebase ID token of user Any
Example
"Authorization: my-firebase-idToken"

Query parameters

▷ Id

MongoDB ID of the Item

Name Type In Description Accepted values
Id (required) string query MongoDB ID of the Item Any
Example
"Id=629cc52563533a84f60c4c68"
▷ User_id

FindNUS User_Id (for lost item lookout requests). Include this to remove from Lost (Lookout) Items collection. Case sensitive.

Name Type In Description Accepted values
User_id string query

FindNUS User_Id (for lost item lookout requests). Include this to remove from Lost (Lookout) Items collection. Case sensitive.

 Any
Example
"User_id=196afas7"

Request body

application/json
Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Example (generated)
{
  "Id": "98721yrr0u14oure"
}

Responses

▶ 200 - Deletion request received and will be processed if the item exists.
Headers

No headers specified

▶ 401 - Firebase credentials not invalid
Headers

No headers specified

GET /item/peek

Get a list of lost items sorted by date. These items are paginated and filtered by category, if requested. The default returns the latest 20 items, with no category filter.

Query parameters

▷ offset

Number of items to skip (Case sensitive)

Name Type In Description Accepted values
offset integer query Number of items to skip (Case sensitive) Any
▷ limit

Number of items to return (Case sensitive)

Name Type In Description Accepted values
limit integer query Number of items to return (Case sensitive) Any
▷ category

Types of category to filter by. Chain multiple category values to filter by the For example, category=Cards&category=Etc will include results from both Cards and Etc.

Name Type In Description Accepted values
category string query

Types of category to filter by. Chain multiple category values to filter by the For example, category=Cards&category=Etc will include results from both Cards and Etc.

 Any
▷ startdate

String representation of the start date to filter by. Date should be in ISO format: YYYY-MM-DDThh:mm:ssZ, eg: 2012:12:25T17:33:59Z

Name Type In Description Accepted values
startdate string query

String representation of the start date to filter by. Date should be in ISO format: YYYY-MM-DDThh:mm:ssZ, eg: 2012:12:25T17:33:59Z

 Any
▷ enddate

String representation of the end date to filter by. Date should be in ISO format: YYYY-MM-DDThh:mm:ssZ, eg: 2012:12:25T17:33:59Z

Name Type In Description Accepted values
enddate string query

String representation of the end date to filter by. Date should be in ISO format: YYYY-MM-DDThh:mm:ssZ, eg: 2012:12:25T17:33:59Z

 Any

Responses

▶ 200 - Returns an array of lost items that may be filtered
Headers

No headers specified

application/json
Name Type Description Accepted values
Response array(object) Any
Response.Id (required) string The MongoDB ObjectID associated to this Item Any
Response.Name (required) string Name of lost/found item Any
Response.Date (required) string Date-time where item is lost/found Any
Response.Location (required) string Where the item was found Any
Response.Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Response.Image_url string Item's accompanying image link Any
Response.Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
[
  {
    "Id": "98721yrr0u14oure",
    "Name": "Water Bottle",
    "Date": "2019-08-24T14:15:22Z",
    "Location": "E4A DSA Lab",
    "Category": "Cards",
    "Image_url": "https://imgur.com/gallery/RaHyECD",
    "Pluscode": "7QXC+CR Singapore"
  }
]
▶ 500 - Internal server error. Likely to be a message queue fault.
Headers

No headers specified

GET /search

Text-based search for an item.

Query parameters

▷ query

Text query to search for lost items. Can be any arbitrary string - the ElasticSearch engine will attempt to best-match the query. The query will be performed over the FOUND collection's Name, Category, Location and Item Detail fields.

Name Type In Description Accepted values
query string query

Text query to search for lost items. Can be any arbitrary string - the ElasticSearch engine will attempt to best-match the query. The query will be performed over the FOUND collection's Name, Category, Location and Item Detail fields.

 Any

Responses

▶ 200 - Returns an array of Found items that were matched to the query string.
Headers

No headers specified

application/json
Name Type Description Accepted values
Response array(object) Any
Response.Id (required) string The MongoDB ObjectID associated to this Item Any
Response.Name (required) string Name of lost/found item Any
Response.Date (required) string Date-time where item is lost/found Any
Response.Location (required) string Where the item was found Any
Response.Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Response.Image_url string Item's accompanying image link Any
Response.Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
[
  {
    "Id": "98721yrr0u14oure",
    "Name": "Water Bottle",
    "Date": "2019-08-24T14:15:22Z",
    "Location": "E4A DSA Lab",
    "Category": "Cards",
    "Image_url": "https://imgur.com/gallery/RaHyECD",
    "Pluscode": "7QXC+CR Singapore"
  }
]
▶ 500 - Internal server error. Likely to be a message queue fault.
Headers

No headers specified

GET /lookout

Get a list of found items that FindNUS decides are a good possible match to the lost item queried.

Query parameters

▷ Id

Id of the lost item

Name Type In Description Accepted values
Id integer query Id of the lost item Any
▷ User_id

User_id of the lost item's owner

Name Type In Description Accepted values
User_id integer query User_id of the lost item's owner Any

Responses

▶ 200 - Returns an array of found items that best match the lost item.
Headers

No headers specified

application/json
Name Type Description Accepted values
Response array(object) Any
Response.Id (required) string The MongoDB ObjectID associated to this Item Any
Response.Name (required) string Name of lost/found item Any
Response.Date (required) string Date-time where item is lost/found Any
Response.Location (required) string Where the item was found Any
Response.Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Response.Image_url string Item's accompanying image link Any
Response.Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
[
  {
    "Id": "98721yrr0u14oure",
    "Name": "Water Bottle",
    "Date": "2019-08-24T14:15:22Z",
    "Location": "E4A DSA Lab",
    "Category": "Cards",
    "Image_url": "https://imgur.com/gallery/RaHyECD",
    "Pluscode": "7QXC+CR Singapore"
  }
]
▶ 400 - Bad request. Missing one or both of User_id and id.
Headers

No headers specified

▶ 500 - Internal server error. Likely to be a message queue fault.
Headers

No headers specified

Schemas

Item

Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Name (required) string Name of lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_url string Item's accompanying image link Any
User_id string UserID associated to this item. Only applicable for Lookout Items. Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag IS REQUIRED.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_url": "https://imgur.com/gallery/RaHyECD",
  "User_id": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}

MiniItem

Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Name (required) string Name of lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Image_url string Item's accompanying image link Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Image_url": "https://imgur.com/gallery/RaHyECD",
  "Pluscode": "7QXC+CR Singapore"
}

NewItem

Name Type Description Accepted values
User_id string Unique User_id generated by firebase to associate a user to a Lookout item. Any
Name (required) string Name of new lost/found item Any
Date (required) string Date-time where item is lost/found Any
Location (required) string Where the item was found Any
Category (required) string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_base64 string Accompanying image of new Lost/Found item, if applicable Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag should only exist for Lost items.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "User_id": "string",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_base64": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}

DeleteItem

Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
Example (generated)
{
  "Id": "98721yrr0u14oure"
}

PatchItem

Name Type Description Accepted values
Id (required) string The MongoDB ObjectID associated to this Item Any
User_id string Unique User_id generated by firebase to associate a user to a Lookout item. Any
Name string Name of new lost/found item Any
Date string Date-time where item is lost/found Any
Location string Where the item was found Any
Category string Type of item Etc, Cards, Notes, Electronics, Bottles
Contact_method string Founder/Lostee Contact Method nus_security, telegram, whatsapp, wechat, line, phone_number
Contact_details string Contact details of Founder/Lostee Any
Item_details string Any
Image_base64 string Updated image of Lost/Found item, if applicable Any
Lookout boolean

Flag determining whether the Lost item has subscribed to the Lookout service. This flag should only exist for Lost items.

 Any
Pluscode string

Pluscode is a string representing the geolocation of a place based on its latitude and longitude. Optional parameter if the lost item is tagged to a particular LAT/LONG

 Any
Example (generated)
{
  "Id": "98721yrr0u14oure",
  "User_id": "string",
  "Name": "Water Bottle",
  "Date": "2019-08-24T14:15:22Z",
  "Location": "E4A DSA Lab",
  "Category": "Cards",
  "Contact_method": "Telegram",
  "Contact_details": "FindNUS",
  "Item_details": "Blue, with a sticker and broken handle",
  "Image_base64": "string",
  "Lookout": false,
  "Pluscode": "7QXC+CR Singapore"
}

Category

Name Type Description Accepted values
Category string Non-case sensitive category name Etc, Cards, Notes, Electronics, Bottles
Example (generated)
"Etc"

ContactMethod

Name Type Description Accepted values
ContactMethod string Non-case sensitive contact method nus_security, telegram, whatsapp, wechat, line, phone_number
Example (generated)
"nus_security"