API Endpoints

API Endpoint Summary

Base URL

The API can be accessed using this URL, in combination with any of the routes in the provided tables.
The <PORT> value should be defined in your backend .env file.

http://localhost:<PORT>

Most of the routes require a firebase token for access.

Users

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/users	Get the currently signed in User	N/A	firebase token	N/A	202 Found if success, with {_id: string, first_name: string, last_name: string } or 404 Not Found if user not found
POST /api/users	Create/register one user with Firebase and store in db	N/A	firebase token	{ first_name: string, last_name: string }	201 Created if success, with { _id: string, first_name: string, last_name: string } or 400 Bad Request

Persons

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/persons/	Get all Persons associated with an authenticated User, can filter with the term param. Response can be paginated using both limit and page params.	N/A	Firebase token term limit page	N/A	200 OK if success, with 401 UNAUTHORIZED If User not authenticated
GET /api/persons/:id	Get one Person associated with an authenticated User	Person's ID	Firebase token	N/A	200 OK if success, with 401 UNAUTHORIZED If User not authenticated 404 NOT FOUND If Person with this ID not found
POST /api/persons	Create one Person and associate it with the given User	N/A	Firebase token		201 CREATED if successful, with 400 Bad Request If Person could not be created 409 Conflict If Person could not be stored in the User
PUT /api/persons/:id	Update one Person associated with an authenticated User	Person's ID	Firebase token		204 NO CONTENT if successful, 401 UNAUTHORIZED if user is not logged in or does not exist in the database, 404 NOT FOUND if the Person does not belong to this User or does not exist in the database
DELETE /api/persons/:id	Deletes one Person associated with an authenticated User	Person's ID	Firebase token	N/A	200 OK if successful, 401 UNAUTHORIZED if a user is not logged in or does not exist in the database, 409 CONFLICT if there is some inconsistency in the database so User could not be updated or Encounters could not be deleted, 404 NOT FOUND if this Person is not associated with the logged-in User
GET /api/persons/companies/:id	Get all Persons associated with a given Company	Company's ID	Firebase token	N/A	200 OK if success, with Array[{ _id: string, first_name: string, last_name: string, birthday: Date, gender: string, location: string, importance_level: Importance, first_met: Date, how_we_met: string, interests: string[], labels: string[], organisation: string, social_media: Map<string, string>, image: Buffer, encounters: mongoose.Types.ObjectId[], companies: mongoose.Types.ObjectId[], time_updated: Date,}] 401 UNAUTHORIZED If User not authenticated 404 NOT FOUND If Company with this ID not found

Encounters

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/encounters	Get all Encounters associated with an authenticated User, can filter with the term param. Response can be paginated using both limit and page params.	N/A	Firebase token term limit page	N/A	200 OK if success, with 401 UNAUTHORIZED If User not authenticated
GET /api/encounters/:id	Get one Encounter associated with an authenticated User	Encounter ID	Firebase token	N/A	200 OK if success, with 401 UNAUTHORIZED If User not authenticated 404 NOT FOUND If Encounter with this ID not found
POST /api/encounters	Create one Encounter and associate it with the given User	N/A	Firebase token		201 CREATED if successful, with 403 Forbidden If Encounter could not be created 409 Conflict If Encounter could not be stored in the User
PUT /api/encounters/:id	Update one Encounter in the db using an ObjectId (string)	Encounter's ID	Firebase token	{date:? Date, time_upated: Date, location?: string, description?: string, persons?: [ObjectId]}	204 No Content if successful, 400 Bad Request if supplied request payload is invalid, 401 Unauthorized if unauthorised
DELETE /api/encounters/:id	Deletes one Encounter associated with an authenticated User	Encounter's ID	Firebase token	N/A	200 OK if successful, 401 UNAUTHORIZED if a user is not logged in or does not exist in the database, 409 CONFLICT if there is some inconsistency in the database so User or Persons could not be updated, 404 NOT FOUND if this Person is not associated with the logged-in User
DELETE /api/encounters/prune:pruneDate	Deletes Encounters associated with an authenticated User that precede input 'pruneDate'	Prune date	Firebase token	N/A	200 OK if successful, 401 UNAUTHORIZED if a user is not logged in or does not exist in the database, 409 CONFLICT if there is some inconsistency in the database so User or Persons could not be updated, 404 NOT FOUND if this Person is not associated with the logged-in User

Birthdays

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/birthdays	Get list of all person objects whose birthdays are within 3 months of todays date	N/A	firebase token	N/A	200 OK if success, with 401 UNAUTHORIZED If User not authenticated

Companies

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/companies	Get all Companies associated with an authenticated User, can filter with the term param. Response can be paginated using both limit and page params.	N/A	Firebase token term limit page	N/A	200 OK if success, with Array[{_id: string, name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] }] 401 UNAUTHORIZED If User not authenticated
GET /api/companies/:id	Get one Company associated with an authenticated User	Company ID	Firebase token	N/A	200 OK if success, with {_id: string, name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] } 401 UNAUTHORIZED If User not authenticated 404 NOT FOUND If Company with this ID not found
POST /api/companies	Create one Company and associate it with the given User	N/A	Firebase token	{name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] }	201 CREATED if successful, with {_id: string, name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] } 403 Forbidden If Company could not be created 409 Conflict If Company could not be stored in the User
PUT /api/companies/:id	Update one Company in the db using an ObjectId (string)	Company's ID	Firebase token	{_id: string, name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] }	204 No Content if successful, 400 Bad Request if supplied request payload is invalid, 401 Unauthorized if User is unauthorised
DELETE /api/companies/:id	Deletes one Company associated with an authenticated User	Company's ID	Firebase token	N/A	200 OK if successful, 401 UNAUTHORIZED if a user is not logged in or does not exist in the database, 409 CONFLICT if there is some inconsistency in the database so User or Persons could not be updated, 404 NOT FOUND if this Person is not associated with the logged-in User

Goal

Route	Description	Path Parameter	Request Header	Request Payload	Response Payload
GET /api/goal/:id	Get one Goal associated with an authenticated User	Goal ID	Firebase token	N/A	200 OK if success, with {_id: string, date_start: Date, date_end: Date, duration: string, encounter_goal: number, recurring: boolean } 401 UNAUTHORIZED If User not authenticated 404 NOT FOUND If Goal with this ID not found
POST /api/goal	Create one Goal and associate it with the given User	N/A	Firebase token	{date_start: Date, date_end: Date, duration: string, encounter_goal: number, recurring: boolean }	201 CREATED if successful, with {_id: string, name: string, location: string, description: string, date_founded: Date, time_updated: Date, image: Buffer, persons: mongoose.Types.ObjectId[] } 403 Forbidden If Goal could not be created 409 Conflict If Goal could not be stored in the User
PUT /api/goal/:id	Update one Goal in the db using an ObjectId (string)	Goal's ID	Firebase token	{_id: string, date_start: Date, date_end: Date, duration: string, encounter_goal: number, recurring: boolean }	204 No Content if successful, 400 Bad Request if supplied request payload is invalid, 401 Unauthorized if User is unauthorised
DELETE /api/goal/:id	Deletes one Goal associated with an authenticated User	Company's ID	Firebase token	N/A	200 OK if successful, 401 UNAUTHORIZED if a user is not logged in or does not exist in the database, 409 CONFLICT if there is some inconsistency in the database so User or Persons could not be updated, 404 NOT FOUND if this Person is not associated with the logged-in User