Actual FindNUS API for Milestone 2

From this line below, it is the Markdown API documentation that is stored on the working backend repository for developers to reference and use.

FindNUS_api

API documentation for FindNUS backend services. Handles the retrieval, processing and management of Lost Items found in NUS.

Servers
Paths
Schemas
- Item
- MiniItem
- NewItem
- DeleteItem
- PatchItem
- Category
- ContactMethod

## 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

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"
}

▶ 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

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"
}

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

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"
}

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

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"
}

▶ 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

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

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"
  }
]

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

Headers

No headers specified

`GET` /search

Text-based search for an item.

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

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"
  }
]

▶ 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

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"
}

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

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"
}

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

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"
}

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

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"
}

Name	Type	Description	Accepted values
Category	string	Non-case sensitive category name	`Etc`, `Cards`, `Notes`, `Electronics`, `Bottles`

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"

Actual FindNUS API for Milestone 2

FindNUS_api

Table of Contents

GET /debug/ping

▶ 200 - A hello world message.

Headers

text/plain

Example

GET /debug/checkAuth

▷ Authorization

Example

Responses

▶ 200 - Id token is valid

Headers

▶ 401 - Id token is invalid

Headers

GET /debug/getDemoItem

▷ name

Responses

▶ 200 - Get request is valid, item is found

Headers

application/json

Example (generated)

▶ 404 - Get request is valid, item not found

Headers

text/plain

Example

POST /item

▷ Authorization

Example

Request body

application/json

Example (generated)

Responses

▶ 200 - Item registered into database

Headers

▶ 400 - Rejected new item into database

Headers

▶ 401 - Firebase credentials not invalid

Headers

PATCH /item

▷ Authorization

Example

Query parameters

▷ Id

Example

▷ User_id

Example

Request body

application/json

Example (generated)

Responses

▶ 200 - OK

Headers

▶ 401 - Firebase credentials not invalid

Headers

GET /item

▷ Id

▷ User_id

Responses

▶ 200 - A Lost Item’s details

Headers

application/json

Example (generated)

▶ 404 - Item not found

Headers

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

Headers

DELETE /item

▷ Authorization

Example

Query parameters

▷ Id

Example

▷ User_id

Example

Request body

application/json

Example (generated)

Responses

`GET` /debug/ping

`GET` /debug/checkAuth

`GET` /debug/getDemoItem

`POST` /item

`PATCH` /item

`GET` /item

`DELETE` /item

`GET` /item/peek

`GET` /search