This is a simple API to manage lost and found items. It is built using Node.js, Express, and MongoDB. It is a RESTful API that uses JSON Web Tokens for authentication. It is a work in progress and is not yet complete.
The following environment variables are required:
# ENV info
PORT=3000
NODE_ENV=dev
# DB connection info
DB_USER=your_db_username
DB_PASSWORD=your_db_password
DB_HOST_PROD=lost-found-api
DB_HOST_TEST=lost-found-api-test
DB_HOST_DEV=lost-found-api-dev
# CORS config
CORS_ORIGIN=https://yourdomain.com
# REQ limit
REQEST_LIMIT_TIMEOUT=xxxx
REQEST_NUMBER_LIMIT=xxxx
# BCRYPT config
BCRYPT_SALT_ROUNDS=xx
BCRYPT_PASSWORD_PEPPER=xxxx
# JWT config
JWT_SECRET=xxxxx
JWT_EXPIRES_IN=xxxx
# URL
DEV_URL=https://localhost:3000
PROD_URL=https://yourdomain.com
- Clone the repository
- Run
npm installto install dependencies - Run
npm startto start the server - Run
npm testto run the tests - Run
npm run devto start the server in development mode - Run
npm run lintto run the linter - Run
npm run formatto format the code using Prettier - Run
npm run buildto build the project for production - Run
npm run cleanto remove the build directory
- Add tests ✅
- Add more endpoints ⏳
- Add more documentation ⏳
- Create a frontend ⏳
- API endpoints is live at
https://lost-found-api.onrender.comfor testing.
The following endpoints are used to manage users:
GET /api/v1/users/:id- Show a user ✅GET /api/v1/users/:id/avatar- Get user avatar ✅POST /api/v1/users/signup- Create a new user ✅POST /api/v1/users/authenticate- Authenticate a user ✅POST /api/v1/users/avatar- Upload user avatar ✅PATCH /api/v1/users/:id- Update a user ✅DELETE /api/v1/users/:id- Delete a user ✅DELETE /api/v1/users/avatar- Delete user avatar ✅
The following endpoints are used to manage items:
GET /api/v1/items- Get all items ✅GET /api/v1/items/:id- Show item ✅GET /api/v1/items/:id/image- Get item image ✅GET /api/v1/items/user/:id- Get user items ✅POST /api/v1/items- Create item ✅POST /api/v1/items/:id/image- Upload item image ✅PATCH /api/v1/items/:id- Update item ✅DELETE /api/v1/items/:id- Delete item ✅
-
POST /api/v1/users/signup- Create a new user 📌✅-
Authorization: None
-
Request body:
phoneNumber- Type:
string - Required:
true - Example:
01234567899 - length:
11
- Type:
password- Type:
string - Required:
true - Example:
9696 - length:
min:4, max:50 characters
- Type:
name- Type:
string - Required:
true - Example:
MOHAMMED - length:
min:2, max:20 characters
- Type:
city- Type:
string - Required:
false - Example:
Alexandria - length:
min:2, max:20 characters
- Type:
country- Type:
string - Required:
false - Example:
Egypt - length:
min:2, max:20 characters
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
User created successfully
- Type:
datatoken- Type:
string
- Type:
useridnamephoneNumbercitycountryavatar
-
-
POST /api/v1/users/authenticate- Authenticate a user 📌✅-
Authorization: None
-
Request body:
phoneNumber- Type:
string - Required:
true - Example:
01234567899 - length:
11
- Type:
password- Type:
string - Required:
true - Example:
9696 - length:
min:2, max:50 characters
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
User authenticated successfully
- Type:
datatoken- Type:
string
- Type:
useridnamephoneNumbercitycountryavatar
-
-
GET /api/v1/users/:id- Show a user 📌✅-
Authorization: None
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
User retrieved successfully
- Type:
datatoken- Type:
string
- Type:
useridnamephoneNumbercitycountryavatar
-
-
PATCH /api/v1/users/:id- Update a user 📌✅-
Authorization:
Bearer token -
Request body:
name- Type:
string - Required:
false - Example:
MOHAMMED - length:
min:2, max:20 characters
- Type:
city- Type:
string - Required:
false - Example:
Alexandria - length:
min:2, max:20 characters
- Type:
country- Type:
string - Required:
false - Example:
Egypt - length:
min:2, max:20 characters
- Type:
phoneNumber- Type:
string - Required:
false - Example:
01234567899 - length:
11
- Type:
password- Type:
string - Required:
false - Example:
9696 - length:
min:2, max:50 characters
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
User Updated successfully
- Type:
datatoken- Type:
string
- Type:
useridnamephoneNumbercitycountryavatar
-
-
DELETE /api/v1/users/:id- Delete a user 📌✅-
Authorization:
Bearer token -
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
User deleted successfully
- Type:
-
-
POST /api/v1/users/avatar- Upload user avatar 📌✅-
Authorization:
Bearer token -
Request body:
avatar- Type:
file - Required:
true - Example:
avatar.png
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Avatar uploaded successfully
- Type:
dataavatar- Type:
string - Example:
https://yourdomain.com/api/v1/users/6351f0b8ae4d15d6d911b417/avatar
- Type:
-
-
DELETE /api/v1/users/avatar- Delete user avatar 📌✅-
Authorization:
Bearer token -
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Image removed successfully
- Type:
-
-
GET /api/v1/users/:id/avatar- Get user avatar 📌✅-
Authorization:
Bearer token -
Response body:
image
-
-
GET /api/v1/items- Get all items 📌✅-
Note: This endpoint is paginated & supports sorting, filtering, and searching (very generic)
-
Use-Case: Recently added items, oldest items, related items, suggested items, etc.
-
EX:
/api/v1/items?limit=3&page=2&sortBy=createdAt&order=desc
-
Authorization: none
-
Query parameters:
page- Type:
number - Required:
false - Example:
page=1
- Type:
limit- Type:
number - Required:
false - Example:
limit=10
- Type:
sortBy- Type:
string - Required:
false - Accepted-values:
createdAt | updatedAt - Example:
sortBy=createdAt
- Type:
order- Type:
string - Required:
false - Accepted-values:
asc | desc - Example:
order=desc
- Type:
-
Request body:
name- Type:
string - Required:
false - Example:
MOHAMMED - length:
min:2, max:50 characters
- Type:
city- Type:
string - Required:
false - Example:
Alexandria - length:
min:2, max:20 characters
- Type:
country- Type:
string - Required:
false - Example:
Egypt - length:
min:2, max:20 characters
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Items fetched successfully
- Type:
dataitemsidnamedescriptioncategorycreatorimagecitycountrycreatedAtupdatedAt
-
-
GET /api/v1/items/:id- Show item 📌✅-
Authorization: none
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Item fetched successfully
- Type:
dataitemidnamedescriptioncategorycreatorimagecitycountrycreatedAtupdatedAt
-
-
POST /api/v1/items- Create item 📌✅-
Authorization:
Bearer token -
Request body:
name- Type:
string - Required:
true - Example:
Iphone 11 - length:
min:2, max:50 characters
- Type:
description- Type:
string - Required:
false - Example:
I found this item in the street at 10:00 am - length:
min:2, max:200 characters
- Type:
category- Type:
string - Required:
true - Example:
mobile - Accepted-values:
mobile | laptop | keys | id | document | money | tablet | watch | camera | other |
- Type:
city- Type:
string - Required:
true - Example:
Alexandria - length:
min:2, max:20 characters
- Type:
country- Type:
string - Required:
true - Example:
Egypt - length:
min:2, max:20 characters
- Type:
creator- Type:
string - Required:
true - Example:
6353252d287fb9b38a22ab57
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Item created successfully
- Type:
dataitemidnamedescriptioncategorycreatorimagecitycountrycreatedAtupdatedAt
-
-
PATCH /api/v1/items/:id- Update item 📌✅-
Authorization:
Bearer token -
Request body:
name- Type:
string - Required:
false - Example:
Iphone 11 - length:
min:2, max:50 characters
- Type:
description- Type:
string - Required:
false - Example:
I found this item in the street at 10:00 am - length:
min:2, max:200 characters
- Type:
category- Type:
string - Required:
false - Example:
mobile - Accepted-values:
mobile | laptop | keys | id | document | money | tablet | watch | camera | other | - length:
min:2, max:20 characters
- Type:
city- Type:
string - Required:
false - Example:
Alexandria - length:
min:2, max:20 characters
- Type:
country- Type:
string - Required:
false - Example:
Egypt - length:
min:2, max:20 characters
- Type:
creator- Type:
string - Required:
false - Example:
6353252d287fb9b38a22ab57
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Item updated successfully
- Type:
dataitemidnamedescriptioncategorycreatorimagecitycountrycreatedAt
-
-
DELETE /api/v1/items/:id- Delete item 📌✅-
Authorization:
Bearer token -
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Item deleted successfully
- Type:
-
-
POST /api/v1/items/:id/image- Upload item image 📌✅-
Authorization:
Bearer token -
Request body:
image- Type:
file - Required:
true - Accepted-types:
image/jpg | image/jpeg | image/png - Example:
image.png
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Item image uploaded successfully
- Type:
dataImage
-
-
GET /api/v1/items/:id/image- Get item image 📌✅-
Authorization: none
-
Response body:
dataImage
-
-
GET /api/v1/items/user/:id- Get user items 📌✅-
EX:
/api/v1/items/user/:id?limit=2&page=1&sort=createdAt&order=asc
-
Authorization: none
-
Query parameters:
page- Type:
number - Required:
false - Example:
page=1
- Type:
limit- Type:
number - Required:
false - Example:
limit=10
- Type:
sortBy- Type:
string - Required:
false - Accepted-values:
createdAt | updatedAt - Example:
sortBy=createdAt
- Type:
order- Type:
string - Required:
false - Accepted-values:
asc | desc - Example:
order=desc
- Type:
-
Response body:
status- Type:
string - Example:
success
- Type:
message- Type:
string - Example:
Items fetched successfully
- Type:
dataitemsidnamedescriptioncategorycreatorimagecitycountrycreatedAtupdatedAt
-