Skip to content

magoma394/CarFinder

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
backend
backend
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
package-lock.json
package-lock.json
 
 

Repository files navigation

Car Project API-Documentation

Overview

The Car Project API provides endpoints for managing a car marketplace, including user authentication, user profile management, admin operations, and car management (new and used cars). The API uses MongoDB Atlas for data storage and JWT for authentication.

  • Base URL: http://localhost:8080/api
  • Authentication: Most endpoints require a JWT token in the Authorization header as Bearer <token>.
  • Content Type: All requests and responses use application/json unless specified otherwise.

Authentication

All protected endpoints require a JWT token obtained via the /auth/login or /auth/register endpoints. Tokens are valid for 24 hours and must be included in the Authorization header.

Error Responses

All endpoints return errors in the following format:

{
  "error": "Error message"
}

Common error codes:

  • 400 Bad Request: Invalid request body or parameters.
  • 401 Unauthorized: Missing or invalid JWT token.
  • 403 Forbidden: Insufficient permissions (e.g., wrong role).
  • 404 Not Found: Resource not found.
  • 500 Internal Server Error: Server-side error.

Endpoints

Authentication

POST /auth/register

Register a new user.

Request:

{
  "email": "string",
  "password": "string",
  "role": "string (buyer|seller|dealer|admin)",
  "first_name": "string",
  "last_name": "string",
  "dealer_details": {
    "company_name": "string",
    "logo_url": "string",
    "address": "string",
    "business_license": "string"
  } // Required for dealer role
}

Response (201 Created):

{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string",
    "role": "string",
    "first_name": "string",
    "last_name": "string"
  }
}

Errors:

  • 400: Invalid request body, email already exists, or invalid role.
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/auth/register \
-H "Content-Type: application/json" \
-d '{
  "email": "user@test.com",
  "password": "Password123!",
  "role": "buyer",
  "first_name": "John",
  "last_name": "Doe"
}'

POST /auth/login

Log in a user and obtain a JWT token.

Request:

{
  "email": "string",
  "password": "string"
}

Response (200 OK):

{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string",
    "role": "string",
    "first_name": "string",
    "last_name": "string"
  }
}

Errors:

  • 400: Invalid request body.
  • 401: Invalid credentials.
  • 500: Database error.

Example:

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

POST /auth/reset-password/request

Request a password reset token.

Request:

{
  "email": "string"
}

Response (200 OK):

{
  "message": "Password reset token sent to email"
}

Errors:

  • 400: Invalid request body.
  • 404: Email not found.
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/auth/reset-password/request \
-H "Content-Type: application/json" \
-d '{
  "email": "user@test.com"
}'

POST /auth/reset-password

Reset a user's password using a token.

Request:

{
  "token": "string",
  "new_password": "string"
}

Response (200 OK):

{
  "message": "Password reset successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Invalid or expired token.
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/auth/reset-password \
-H "Content-Type: application/json" \
-d '{
  "token": "reset_token",
  "new_password": "NewPassword123!"
}'

User Management

GET /users/me

Get the authenticated user's profile.

Headers:

  • Authorization: Bearer <token>

Response (200 OK):

{
  "id": "string",
  "email": "string",
  "role": "string",
  "first_name": "string",
  "last_name": "string",
  "seller_details": {
    "car_count": 0
  }, // Optional, for sellers
  "dealer_details": {
    "company_name": "string",
    "logo_url": "string",
    "address": "string",
    "business_license": "string"
  } // Optional, for dealers
}

Errors:

  • 401: Unauthorized.
  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/users/me \
-H "Authorization: Bearer <token>"

PUT /users/me

Update the authenticated user's profile.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "first_name": "string",
  "last_name": "string",
  "dealer_details": {
    "company_name": "string",
    "logo_url": "string",
    "address": "string",
    "business_license": "string"
  } // Optional, for dealers
}

Response (200 OK):

{
  "message": "Profile updated successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 500: Database error.

Example:

curl -X PUT http://localhost:8080/api/users/me \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
  "first_name": "Jane",
  "last_name": "Doe"
}'

Admin Operations

GET /admin/users

List all users (admin only).

Headers:

  • Authorization: Bearer <token>

Response (200 OK):

[
  {
    "id": "string",
    "email": "string",
    "role": "string",
    "first_name": "string",
    "last_name": "string"
  }
]

Errors:

  • 401: Unauthorized.
  • 403: Forbidden (not admin).
  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/admin/users \
-H "Authorization: Bearer <admin_token>"

DELETE /admin/users/delete

Delete a user by email (admin only).

Headers:

  • Authorization: Bearer <token>

Request:

{
  "email": "string"
}

Response (200 OK):

{
  "message": "User deleted successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 403: Forbidden (not admin).
  • 404: User not found.
  • 500: Database error.

Example:

curl -X DELETE http://localhost:8080/api/admin/users/delete \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <admin_token>" \
-d '{
  "email": "user@test.com"
}'

Car Management

GET /cars

Get all cars (new and used).

Response (200 OK):

[
  {
    "id": "string",
    "name": "string",
    "brand": "string",
    "condition": "string (New|Used)",
    // New car fields
    "type": "string",
    "official_price": "string",
    "photo_link": "string",
    "engine": "string",
    "horsepower": "string",
    "transmission": "string",
    "fuel_efficiency": "string",
    "dimensions": {
      "height": "string",
      "length": "string",
      "width": "string"
    },
    "safety_features": ["string"],
    "technology": ["string"],
    "price_changes": { "year": "price" },
    "trending": false,
    // Used car fields
    "body_type": "string",
    "year": 0,
    "price": "string",
    "photos": ["string"],
    "km": 0,
    "variant": "string",
    "city": "string",
    "color": "string",
    "features": ["string"],
    "condition_en": "string",
    "condition_ar": "string",
    "good_price": false
  }
]

Errors:

  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/cars

GET /cars/{id}

Get a car by ID.

Parameters:

  • id: Car ID (path parameter).

Response (200 OK):

{
  "id": "string",
  "name": "string",
  "brand": "string",
  "condition": "string (New|Used)",
  // Other fields as above
}

Errors:

  • 404: Car not found.
  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/cars/550e8400-e29b-41d4-a716-446655440000

GET /cars/type/{type}

Get cars by type (e.g., SUV, Sedan).

Parameters:

  • type: Car type (path parameter).

Response (200 OK):

[
  {
    "id": "string",
    "name": "string",
    "brand": "string",
    "type": "string",
    // Other fields
  }
]

Errors:

  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/cars/type/SUV

GET /cars/trending

Get trending cars.

Response (200 OK):

[
  {
    "id": "string",
    "name": "string",
    "brand": "string",
    "trending": true,
    // Other fields
  }
]

Errors:

  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/cars/trending

GET /cars/search

Search cars by query parameters.

Parameters:

  • brand: Brand name (query parameter).
  • name: Car name (query parameter).
  • type: Car type (query parameter).
  • condition: New or Used (query parameter).

Response (200 OK):

[
  {
    "id": "string",
    "name": "string",
    "brand": "string",
    // Other fields
  }
]

Errors:

  • 500: Database error.

Example:

curl -X GET http://localhost:8080/api/cars/search?brand=BMW&type=SUV

POST /cars/new/{brand}

Add a new car (dealers and admins only).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).

Request:

{
  "name": "string",
  "type": "string",
  "year": 0,
  "official_price": "string",
  "photo_link": "string",
  "engine": "string",
  "horsepower": "string",
  "transmission": "string",
  "fuel_efficiency": "string",
  "dimensions": {
    "height": "string",
    "length": "string",
    "width": "string"
  },
  "safety_features": ["string"],
  "technology": ["string"],
  "price_changes": { "year": "price" },
  "trending": false
}

Response (201 Created):

{
  "message": "New car added successfully",
  "id": "string"
}

Errors:

  • 400: Invalid request body, missing required fields.
  • 401: Unauthorized.
  • 403: Forbidden (not dealer or admin).
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/cars/new/BMW \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <dealer_token>" \
-d '{
  "name": "X1 M Sport 2024",
  "type": "SUV",
  "year": 2024,
  "official_price": "3,100,000 EGP",
  "photo_link": "https://media.hatla2eestatic.com/uploads/ncarmodel/11294/big-up_ebf5282033826d23fa35347fb5ee77d3.png",
  "engine": "1.5L Turbo",
  "horsepower": "140",
  "transmission": "Automatic",
  "fuel_efficiency": "6.0 L/100km",
  "dimensions": {
    "height": "1,598 mm",
    "length": "4,439 mm",
    "width": "1,821 mm"
  },
  "safety_features": ["ABS", "Airbags"],
  "technology": ["BMW Live Cockpit Professional"],
  "price_changes": {"2024": "3,100,000 EGP"}
}'

DELETE /cars/new/{brand}/{id}

Delete a new car (dealers and admins only).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Response (200 OK):

{
  "message": "New car deleted successfully"
}

Errors:

  • 401: Unauthorized.
  • 403: Forbidden (not dealer or admin).
  • 404: Car not found.
  • 500: Database error.

Example:

curl -X DELETE http://localhost:8080/api/cars/new/BMW/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <dealer_token>"

POST /cars/used/{brand}

Add a used car (buyers, sellers, dealers, admins).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).

Request:

{
  "name": "string",
  "body_type": "string",
  "year": 0,
  "price": "string",
  "photos": ["string"],
  "km": 0,
  "variant": "string",
  "city": "string",
  "color": "string",
  "transmission": "string",
  "features": ["string"],
  "condition_en": "string",
  "condition_ar": "string",
  "good_price": false
}

Response (201 Created):

{
  "message": "Used car added successfully",
  "id": "string"
}

Errors:

  • 400: Invalid request body, missing required fields.
  • 401: Unauthorized.
  • 403: Forbidden (seller car limit reached).
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/cars/used/Nissan \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <buyer_token>" \
-d '{
  "name": "Sentra",
  "body_type": "Sedan",
  "year": 2025,
  "price": "965,000 EGP",
  "photos": ["https://media.hatla2eestatic.com/uploads/car/2025/01/13/6880814/full_up_0b298e9515f1359eab0d8ba0258745b0.jpg"],
  "km": 2000,
  "variant": "Automatic / Highline",
  "city": "New Cairo",
  "color": "Dark Red",
  "transmission": "Automatic"
}'

PUT /cars/used/{brand}/{id}

Update a used car (buyers, sellers, dealers, admins).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Request:

{
  "name": "string",
  "body_type": "string",
  "year": 0,
  "price": "string",
  "photos": ["string"],
  "km": 0,
  "variant": "string",
  "city": "string",
  "color": "string",
  "transmission": "string",
  "features": ["string"],
  "condition_en": "string",
  "condition_ar": "string",
  "good_price": false
}

Response (200 OK):

{
  "message": "Car updated successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 404: Car not found.
  • 500: Database error.

Example:

curl -X PUT http://localhost:8080/api/cars/used/Nissan/123e4567-e89b-12d3-a456-426614174000 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <buyer_token>" \
-d '{
  "name": "Sentra",
  "body_type": "Sedan",
  "year": 2025,
  "price": "950,000 EGP",
  "photos": ["https://media.hatla2eestatic.com/uploads/car/2025/01/13/6880814/full_up_0b298e9515f1359eab0d8ba0258745b0.jpg"],
  "km": 2500,
  "variant": "Automatic / Highline",
  "city": "New Cairo",
  "color": "Dark Red",
  "transmission": "Automatic"
}'

DELETE /cars/used/{brand}/{id}

Delete a used car (buyers, sellers, dealers, admins).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Response (200 OK):

{
  "message": "Car deleted successfully"
}

Errors:

  • 401: Unauthorized.
  • 404: Car not found.
  • 500: Database error.

Example:

curl -X DELETE http://localhost:8080/api/cars/used/Nissan/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer <buyer_token>"

POST /cars/used/{brand}/{id}/photos

Add a photo to a used car.

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Request:

{
  "photo_url": "string"
}

Response (200 OK):

{
  "message": "Photo added successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 404: Car not found.
  • 500: Database error.

Example:

curl -X POST http://localhost:8080/api/cars/used/Nissan/123e4567-e89b-12d3-a456-426614174000/photos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <buyer_token>" \
-d '{
  "photo_url": "https://example.com/photo.jpg"
}'

DELETE /cars/used/{brand}/{id}/photos

Remove a photo from a used car.

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Request:

{
  "photo_url": "string"
}

Response (200 OK):

{
  "message": "Photo removed successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 404: Car or photo not found.
  • 500: Database error.

Example:

curl -X DELETE http://localhost:8080/api/cars/used/Nissan/123e4567-e89b-12d3-a456-426614174000/photos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <buyer_token>" \
-d '{
  "photo_url": "https://example.com/photo.jpg"
}'

PUT /cars/new/{brand}/{id}/photo

Update the photo link for a new car (dealers and admins only).

Headers:

  • Authorization: Bearer <token>

Parameters:

  • brand: Car brand (path parameter).
  • id: Car ID (path parameter).

Request:

{
  "photo_link": "string"
}

Response (200 OK):

{
  "message": "Photo updated successfully"
}

Errors:

  • 400: Invalid request body.
  • 401: Unauthorized.
  • 403: Forbidden (not dealer or admin).
  • 404: Car not found.
  • 500: Database error.

Example:

curl -X PUT http://localhost:8080/api/cars/new/BMW/550e8400-e29b-41d4-a716-446655440000/photo \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <dealer_token>" \
-d '{
  "photo_link": "https://example.com/new_photo.jpg"
}'

Database Schema

  • newCars Collection:

    {
  "BMW": {
    "models": [
      {
        "id": "uuid",
        "name": "string",
        "brand": "string",
        "type": "string",
        "year": 0,
        "official_price": "string",
        "photo_link": "string",
        "condition": "New",
        "engine": "string",
        "horsepower": "string",
        "transmission": "string",
        "fuel_efficiency": "string",
        "dimensions": {
          "height": "string",
          "length": "string",
          "width": "string"
        },
        "safety_features": ["string"],
        "technology": ["string"],
        "price_changes": { "year": "price" },
        "trending": false
      }
    ]
  }
}

  • usedCars Collection:

    {
  "Nissan": {
    "models": [
      {
        "id": "uuid",
        "name": "string",
        "brand": "string",
        "body_type": "string",
        "year": 0,
        "price": "string",
        "photos": ["string"],
        "condition": "Used",
        "km": 0,
        "variant": "string",
        "city": "string",
        "color": "string",
        "transmission": "string",
        "features": ["string"],
        "condition_en": "string",
        "condition_ar": "string",
        "good_price": false
      }
    ]
  }
}

  • users Collection:

    {
  "_id": "string",
  "email": "string",
  "password": "string",
  "role": "string (buyer|seller|dealer|admin)",
  "first_name": "string",
  "last_name": "string",
  "seller_details": {
    "car_count": 0
  },
  "dealer_details": {
    "company_name": "string",
    "logo_url": "string",
    "address": "string",
    "business_license": "string"
  },
  "verified": true,
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

  • password_reset_tokens Collection:

    {
  "user_id": "string",
  "token": "string",
  "expires_at": "timestamp"
}

Notes

  • JWT Secret: The JWT secret is hardcoded as iamsecret. For production, use an environment variable.
  • MongoDB: The API uses MongoDB Atlas with the connection string in db.go. Ensure the connection string is valid.
  • Seller Limit: Sellers can list up to 2 used cars.
  • Indexes: Unique indexes are created on users.email, password_reset_tokens.token, and car IDs in newCars and usedCars collections.
  • Testing: Use tools like Postman or curl to test endpoints. Save JWT tokens in variables for convenience.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages