mazyar/tm_back
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c817e2cd3ed9049e22ffa5b580756490ca09b8a
tm_back/docs/examples/API_EXAMPLES.md
T
n.nakhostin 9119e2383e Add configuration file and update server settings 
- Introduced a new `config.yaml` file for managing server, database, cache, queue, AI, scraping, logging, and rate limiting configurations.
- Updated `docker-compose.yml` to reflect the new server port (8081) and adjusted health check endpoints accordingly.
- Modified `Dockerfile` to expose the new server port.
- Updated `README.md` to reflect changes in server configuration and added documentation for the new configuration structure.
- Added test scripts for server and Swagger documentation testing.
- Refactored customer domain structure to align with new configuration settings and improve maintainability.
2025-08-02 12:37:04 +03:30

11 KiB
Raw Blame History

API Examples

This document provides examples of how to interact with the Tender Management API using curl commands.

Prerequisites

  1. Start MongoDB:

    sudo systemctl start mongod

  2. Start the server:

    make run

  3. Verify server is running:

    curl http://localhost:8081/health

Customer Management Examples

1. Register a New Customer (Admin Only)

curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "password": "securepassword123",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg"
  }'

Expected Response:

{
  "success": true,
  "message": "Customer registered successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}

2. Customer Login

curl -X POST http://localhost:8081/api/customers/login \
  -H "Content-Type: application/json" \
  -d '{
    "email_or_mobile": "john@example.com",
    "password": "securepassword123"
  }'

Expected Response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "full_name": "John Doe",
      "username": "johndoe",
      "email": "john@example.com",
      "mobile": "+1234567890",
      "national_id": "123456789",
      "gender": "male",
      "birthdate": 631152000,
      "profile_image": "https://example.com/avatar.jpg",
      "status": "active",
      "is_verified": false,
      "created_at": 1703123456,
      "updated_at": 1703123456
    },
    "access_token": "abc123def456",
    "refresh_token": "xyz789uvw012",
    "expires_at": 1703127056
  }
}

3. Get Customer Profile (Protected)

curl -X GET http://localhost:8081/api/customers/profile \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000"

Expected Response:

{
  "success": true,
  "message": "Profile retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}

4. Update Customer Profile (Protected)

curl -X PUT http://localhost:8081/api/customers/profile \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "full_name": "John Smith",
    "profile_image": "https://example.com/new-avatar.jpg"
  }'

Expected Response:

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Smith",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/new-avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}

5. Change Password (Protected)

curl -X PUT http://localhost:8081/api/customers/change-password \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "old_password": "securepassword123",
    "new_password": "newsecurepassword456"
  }'

Expected Response:

{
  "success": true,
  "message": "Password changed successfully",
  "data": null
}

6. Add Device Token (Protected)

curl -X POST http://localhost:8081/api/customers/device-token \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456",
    "device_type": "android"
  }'

Expected Response:

{
  "success": true,
  "message": "Device token added successfully",
  "data": null
}

7. Remove Device Token (Protected)

curl -X DELETE http://localhost:8081/api/customers/device-token \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456"
  }'

Expected Response:

{
  "success": true,
  "message": "Device token removed successfully",
  "data": null
}

8. Logout (Protected)

curl -X POST http://localhost:8081/api/customers/logout \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456"
  }'

Expected Response:

{
  "success": true,
  "message": "Logged out successfully",
  "data": null
}

Admin Management Examples

9. List All Customers (Admin Only)

curl -X GET "http://localhost:8081/api/admin/customers?limit=10&offset=0&search=john&status=active" \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "Customers retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "full_name": "John Smith",
      "username": "johndoe",
      "email": "john@example.com",
      "mobile": "+1234567890",
      "national_id": "123456789",
      "gender": "male",
      "birthdate": 631152000,
      "profile_image": "https://example.com/new-avatar.jpg",
      "status": "active",
      "is_verified": false,
      "created_at": 1703123456,
      "updated_at": 1703123456
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

10. Get Customer by ID (Admin Only)

curl -X GET http://localhost:8081/api/admin/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Smith",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/new-avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}

11. Update Customer Status (Admin Only)

curl -X PUT http://localhost:8081/api/admin/customers/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended"
  }'

Expected Response:

{
  "success": true,
  "message": "Customer status updated successfully",
  "data": null
}

12. Get All Device Tokens (Admin Only)

curl -X GET http://localhost:8081/api/admin/customers/device-tokens \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "Device tokens retrieved successfully",
  "data": [
    {
      "token": "fcm_token_123456",
      "device_type": "android",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Error Examples

13. Invalid Email Format

curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "invalid-email",
    "mobile": "+1234567890",
    "password": "securepassword123"
  }'

Expected Response:

{
  "success": false,
  "message": "Validation failed",
  "error": "Email: invalid-email does not validate as email"
}

14. Duplicate Email

curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "username": "janedoe",
    "email": "john@example.com",
    "mobile": "+1234567891",
    "password": "securepassword123"
  }'

Expected Response:

{
  "success": false,
  "message": "email already exists",
  "error": "email already exists"
}

15. Invalid Authentication

curl -X GET http://localhost:8081/api/customers/profile

Expected Response:

{
  "success": false,
  "message": "Invalid authentication",
  "error": "Missing customer ID"
}

Testing Script

You can use the following script to test all endpoints:

#!/bin/bash

BASE_URL="http://localhost:8081"

echo "Testing Tender Management API..."

# Test health endpoint
echo "1. Testing health endpoint..."
curl -s "$BASE_URL/health" | jq .

# Register a customer
echo "2. Registering a customer..."
CUSTOMER_RESPONSE=$(curl -s -X POST "$BASE_URL/api/admin/customers/register" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Test User",
    "username": "testuser",
    "email": "test@example.com",
    "mobile": "+1234567890",
    "password": "password123"
  }')

echo "$CUSTOMER_RESPONSE" | jq .

# Extract customer ID
CUSTOMER_ID=$(echo "$CUSTOMER_RESPONSE" | jq -r '.data.id')

if [ "$CUSTOMER_ID" != "null" ]; then
    echo "Customer ID: $CUSTOMER_ID"
    
    # Test login
    echo "3. Testing login..."
    curl -s -X POST "$BASE_URL/api/customers/login" \
      -H "Content-Type: application/json" \
      -d '{
        "email_or_mobile": "test@example.com",
        "password": "password123"
      }' | jq .
    
    # Test get profile
    echo "4. Testing get profile..."
    curl -s -X GET "$BASE_URL/api/customers/profile" \
      -H "X-Customer-ID: $CUSTOMER_ID" | jq .
    
    # Test list customers (admin)
    echo "5. Testing list customers..."
    curl -s -X GET "$BASE_URL/api/admin/customers" | jq .
fi

echo "Testing completed!"

Notes

  1. Authentication: Currently using a simple header-based authentication (X-Customer-ID). In production, this should be replaced with proper JWT token validation.

  2. Timestamps: All timestamps are Unix timestamps (int64) for consistency.

  3. Validation: All requests are validated using govalidator with custom validation rules.

  4. Error Handling: All errors return consistent JSON responses with appropriate HTTP status codes.

  5. CORS: The server is configured to allow all origins for development. Configure properly for production.

Reference in New Issue View Git Blame Copy Permalink