SOKOGO Classifieds Backend API

A comprehensive backend API for the SOKOGO classifieds platform, supporting user authentication and item listings.

Features

• User Authentication: Register, login, and JWT-based authentication
• Item Management: Create, read, update, delete classifieds listings
• Search & Filtering: Advanced search and filtering capabilities
• Category Support: Motors, Property, and Electronics categories

Tech Stack

• Node.js - Runtime environment
• Express.js - Web framework
• MongoDB - Database
• Mongoose - ODM for MongoDB
• JWT - Authentication
• bcrypt - Password hashing
• CORS - Cross-origin resource sharing

Installation

1. Clone the repository:

git clone <repository-url>
cd sokogo_backend

2. Install dependencies:

npm install

3. Create a .env file in the root directory with the following variables:

mongoUrl=mongodb://localhost:27017/sokogo_backend
key=sokogo_secret_key_2024
port=8080

4. Start the server:

# Development mode
npm run server

# Production mode
npm start

API Endpoints

Authentication

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login user
• GET /api/auth/users - Get all users (with pagination and filtering)
• GET /api/auth/users/:userId - Get user by ID

Items (Classifieds)

• GET /api/items - Get all items with filtering
• GET /api/items/:itemId - Get item by ID
• GET /api/items/popular/:category - Get popular items by category
• POST /api/items - Create new item (authenticated)
• POST /api/items/bulk - Create multiple items (authenticated)
• PUT /api/items/:itemId - Update item (authenticated)
• DELETE /api/items/:itemId - Delete item (authenticated)
• GET /api/items/seller/my-items - Get user's items (authenticated)

Data Models

User

{
  firstName: String,
  lastName: String,
  email: String (unique),
  phoneNumber: String,
  password: String (hashed),
  role: String (buyer|seller|admin, default: buyer),
  createdAt: Date
}

Item

{
  title: String,
  description: String,
  category: String (MOTORS|PROPERTY|ELECTRONICS),
  subcategory: String,
  price: Number,
  currency: String,
  location: {
    district: String,
    city: String,
    address: String
  },
  images: [String],
  seller: ObjectId (ref: User),
  status: String (ACTIVE|SOLD|EXPIRED|SUSPENDED),
  features: Object,
  contactInfo: {
    phone: String,
    email: String
  }
}

Authentication

The API uses User ID authentication. Include the user ID in the request headers:

userid: <your_user_id>

or

user-id: <your_user_id>

Example Usage

Register a new user

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "+250123456789",
    "password": "password123",
    "role": "seller"
  }'

Login

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "password123"
  }'

Create an item listing

curl -X POST http://localhost:8080/api/items \
  -H "Content-Type: application/json" \
  -H "userid: <your_user_id>" \
  -d '{
    "title": "Kia Sorento DLX AWD",
    "description": "Excellent condition SUV",
    "category": "MOTORS",
    "subcategory": "CARS",
    "price": 12000000,
    "location": {
      "district": "Kigali",
      "city": "Kigali",
      "address": "Kabeza"
    },
    "features": {
      "brand": "Kia",
      "model": "Sorento",
      "year": 2016,
      "mileage": 82100,
      "fuelType": "Petrol",
      "transmission": "Automatic"
    }
  }'

Environment Variables

• mongoUrl: MongoDB connection URL
• key: Secret key for JWT token generation
• port: Port number for the server

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the ISC License.