{"id":30892375,"url":"https://github.com/angel-iscoding/roomiez-api","last_synced_at":"2025-09-08T19:44:58.390Z","repository":{"id":312002962,"uuid":"1039763528","full_name":"angel-iscoding/RoomieZ-API","owner":"angel-iscoding","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-02T16:59:37.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T17:39:58.206Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/angel-iscoding.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-17T23:47:22.000Z","updated_at":"2025-09-01T04:01:05.000Z","dependencies_parsed_at":"2025-09-02T17:39:58.726Z","dependency_job_id":null,"html_url":"https://github.com/angel-iscoding/RoomieZ-API","commit_stats":null,"previous_names":["angel-iscoding/rommiez-api","angel-iscoding/roomiez-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/angel-iscoding/RoomieZ-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angel-iscoding%2FRoomieZ-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angel-iscoding%2FRoomieZ-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angel-iscoding%2FRoomieZ-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angel-iscoding%2FRoomieZ-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angel-iscoding","download_url":"https://codeload.github.com/angel-iscoding/RoomieZ-API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angel-iscoding%2FRoomieZ-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231433,"owners_count":25245585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-08T19:44:56.953Z","updated_at":"2025-09-08T19:44:58.376Z","avatar_url":"https://github.com/angel-iscoding.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏠 RoomieZ API\n\nA comprehensive RESTful API for student accommodation management, connecting students with landlords for room rentals.\n\n## 🚀 Quick Start\n\n### Option 1: Development with JSON Server (Mock Data)\n\n1. **Install dependencies:**\n\t```bash\n\tnpm install\n\t```\n\n2. **Start JSON server with mock data:**\n\t```bash\n\tnpm run start-json\n\t```\n\n3. **Access the API:** [http://localhost:3099](http://localhost:3099)\n\n### Option 2: Full Development with MySQL Database\n\n1. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n2. **Start with Docker (recommended):**\n   ```bash\n   docker-compose up --build\n   ```\n\n3. **Access the API:** [http://localhost:3010/api/V1](http://localhost:3010/api/V1)\n\n### Option 3: Local Development\n\n1. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n2. **Configure environment variables:**\n   Create a `.env` file in the root directory:\n   ```env\n   PORT=3010\n   DB_HOST=localhost\n   DB_USER=your_mysql_user\n   DB_PASSWORD=your_mysql_password\n   DB_DATABASE=RoomieZ\n   DB_PORT=3306\n   ```\n\n3. **Start the development server:**\n   ```bash\n   npm run dev\n   ```\n\n## 📋 API Documentation\n\n### Base URL\n- **Development:** `http://localhost:3010/api/V1`\n- **Production:** `https://your-domain.com/api/V1`\n\n### 👥 User Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/users` | Get all users |\n| `GET` | `/users/:id` | Get user by ID |\n| `GET` | `/users/:id/exists` | Check if user exists |\n| `GET` | `/users/:id/contacts` | Get user social contacts |\n| `POST` | `/users` | Create new user |\n| `POST` | `/users/check-email` | Check if email is registered |\n| `POST` | `/users/:id/contacts` | Create/update user contacts |\n| `PUT` | `/users/:id` | Update user information |\n| `DELETE` | `/users/:id` | Delete user |\n\n### 🏡 Room Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/roomz` | Get all rooms |\n| `GET` | `/roomz/type/:type` | Get rooms by type |\n| `GET` | `/roomz/user/:userId` | Get all rooms for a specific user |\n| `GET` | `/roomz/:id` | Get room by ID |\n| `POST` | `/roomz` | Create new room |\n| `PUT` | `/roomz/:id` | Update room information |\n| `DELETE` | `/roomz/:id` | Delete room |\n\n### Valid Room Types\n- `studio` - Studio apartment\n- `apartment` - Regular apartment\n- `residential_complex` - Residential complex\n\n### Valid User Roles\n- `student` - Student looking for accommodation\n- `landlord` - Property owner offering rooms\n\n## 🗄️ Database Schema\n\nThe API uses MySQL with the following main tables:\n\n- **users** - User information (students and landlords)\n- **roomz** - Room listings and details\n- **bookings** - Reservation management\n- **transactions** - Payment tracking\n- **contact** - User social media and contact information\n\n## 🧪 Testing with Postman\n\nA complete Postman collection is available in the `Utils/` folder:\n\n1. **Import the collection:**\n   - Open Postman\n   - Go to File → Import\n   - Select `Utils/RommieZ-API-Postman-Collection.json`\n\n2. **Configure environment:**\n   - Set `base_url` to `http://localhost:3010/api/V1`\n\n3. **Test the endpoints:**\n   - All endpoints include example requests and responses\n   - Validation tests are included\n\n## 📁 Project Structure\n\n```\nRommieZ-API/\n├── src/\n│   ├── config/           # Database and environment configuration\n│   ├── controller/       # Request handlers\n│   ├── database/         # Database scripts and mock data\n│   ├── router/           # Route definitions\n│   ├── service/          # Business logic layer\n│   └── server.js         # Express server setup\n├── Utils/                # Postman collection and utilities\n├── docker-compose.yml    # Docker configuration\n├── Dockerfile           # Docker image definition\n└── index.js             # Application entry point\n```\n\n## 🔧 Development Scripts\n\n```bash\n# Start development server with nodemon\nnpm run dev\n\n# Start production server\nnpm start\n\n# Start JSON server (mock data)\nnpm run start-json\n```\n\n## 🐳 Docker Support\n\nThe project includes full Docker support:\n\n```bash\n# Build and start all services\ndocker-compose up --build\n\n# Start in background\ndocker-compose up -d\n\n# Stop services\ndocker-compose down\n\n# Reset database (remove volumes)\ndocker-compose down -v\n```\n\n## 🔒 Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Server port | `3010` |\n| `DB_HOST` | MySQL host | `localhost` |\n| `DB_USER` | MySQL username | - |\n| `DB_PASSWORD` | MySQL password | - |\n| `DB_DATABASE` | Database name | `RoomieZ` |\n| `DB_PORT` | MySQL port | `3306` |\n\n## 📄 Example Requests\n\n### Create a new user\n```bash\nPOST /api/V1/users\nContent-Type: application/json\n\n{\n  \"first_name\": \"John\",\n  \"middle_name\": \"Michael\",\n  \"last_name\": \"Doe\",\n  \"username\": \"johndoe\",\n  \"email\": \"john.doe@email.com\",\n  \"password\": \"securepassword123\",\n  \"city\": \"Barranquilla\",\n  \"birthdate\": \"1998-05-15\",\n  \"role\": \"student\"\n}\n```\n\n### Create a new room listing\n```bash\nPOST /api/V1/roomz\nContent-Type: application/json\n\n{\n  \"user_id\": 2,\n  \"title\": \"Cozy Studio Near University\",\n  \"subtitle\": \"Perfect for students\",\n  \"details\": \"WiFi, utilities included\",\n  \"description\": \"A comfortable studio apartment perfect for students, located near the university campus.\",\n  \"address\": \"123 University Ave, Barranquilla\",\n  \"price\": 350.00,\n  \"roomz_type\": \"studio\",\n  \"is_available\": true\n}\n```\n\n## 🚦 Response Format\n\nAll API responses follow a consistent format:\n\n### Success Response\n```json\n{\n  \"message\": \"Operation completed successfully\",\n  \"data\": { /* response data */ }\n}\n```\n\n### Error Response\n```json\n{\n  \"error\": \"Error description\",\n  \"details\": \"Detailed error message\"\n}\n```\n\n## 🛠️ Technologies Used\n\n- **Node.js** - Runtime environment\n- **Express.js** - Web framework\n- **MySQL** - Database\n- **Docker** - Containerization\n- **mysql2** - MySQL driver for Node.js\n- **cors** - Cross-origin resource sharing\n- **dotenv** - Environment variable management\n\n## 📝 License\n\nThis project is licensed under the ISC License.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📞 Support\n\nFor questions or support, please contact the development team or create an issue in the repository.\n\n---\n\n**Happy coding! 🎉**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangel-iscoding%2Froomiez-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangel-iscoding%2Froomiez-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangel-iscoding%2Froomiez-api/lists"}