The Logistics Microservice provides REST APIs for managing delivery operations with integrated fraud detection. This document outlines the API design, endpoints, data contracts, and integration patterns for frontend and other services.

• Stateless: Each request contains all necessary information
• Resource-based URLs: Clear, hierarchical URI structure
• HTTP Methods: Proper use of GET, POST, PATCH for operations
• Status Codes: Meaningful HTTP status codes

• URL Path Versioning: /api/v1/ prefix for all endpoints
• Backward Compatibility: Maintain compatibility within major versions
• Deprecation Policy: 6-month notice for breaking changes

• Base URL: http://localhost:8080/api
• Protocol: HTTP/HTTPS
• Content-Type: application/json
• Character Encoding: UTF-8

• Authentication: Currently not implemented
• Security: Consider implementing JWT or OAuth2 for production

Authorization: Bearer <token>

Endpoint: POST /v1/deliveries

Description: Creates a new delivery with fraud detection validation

Request Body:

{
  "orderId": "ORD-12345",
  "destinationType": "HOME",
  "recipient": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "[email protected]"
  }
}

Response (201 Created):

{
  "id": 1,
  "orderId": "ORD-12345",
  "destinationType": "HOME",
  "status": "CREATED",
  "recipient": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "[email protected]"
  },
  "createdAt": "2025-05-16T10:00:00",
  "updatedAt": "2025-05-16T10:00:00"
}

Error Responses:

• 400 Bad Request: Invalid input or fraud detection flag
• 500 Internal Server Error: Server processing error

Endpoint: GET /v1/deliveries/{orderId}

Description: Retrieves a specific delivery by its order ID

Path Parameters:

• orderId (string): Unique order identifier

Response (200 OK):

{
  "id": 1,
  "orderId": "ORD-12345",
  "destinationType": "HOME",
  "status": "CREATED",
  "recipient": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "[email protected]"
  },
  "createdAt": "2025-05-16T10:00:00",
  "updatedAt": "2025-05-16T10:00:00"
}

Error Responses:

• 404 Not Found: Delivery not found

Endpoint: GET /v1/deliveries

Description: Retrieves deliveries filtered by status

Query Parameters:

• status (optional): Filter by delivery status
  • Valid values: CREATED, IN_TRANSIT, DELIVERED, FAILED
  • Default: CREATED if not specified

Response (200 OK):

[
  {
    "id": 1,
    "orderId": "ORD-12345",
    "destinationType": "HOME",
    "status": "CREATED",
    "recipient": {
      "name": "John Doe",
      "phone": "+1234567890",
      "email": "[email protected]"
    },
    "createdAt": "2025-05-16T10:00:00",
    "updatedAt": "2025-05-16T10:00:00"
  }
]

Error Responses:

• 400 Bad Request: Invalid status value

Endpoint: PATCH /v1/deliveries/{orderId}/status

Description: Updates the status of a specific delivery

Path Parameters:

• orderId (string): Unique order identifier

Query Parameters:

• status (required): New delivery status
  • Valid values: CREATED, IN_TRANSIT, DELIVERED, FAILED

Response (200 OK):

{
  "id": 1,
  "orderId": "ORD-12345",
  "destinationType": "HOME",
  "status": "IN_TRANSIT",
  "recipient": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "[email protected]"
  },
  "createdAt": "2025-05-16T10:00:00",
  "updatedAt": "2025-05-16T10:30:00"
}

Error Responses:

• 400 Bad Request: Invalid status value
• 404 Not Found: Delivery not found

CREATED       - Initial status when delivery is created
IN_TRANSIT    - Delivery is being processed/shipped
DELIVERED     - Successfully delivered
FAILED        - Delivery failed

HOME          - Home delivery
BUSINESS      - Business/office delivery
PICKUP_POINT  - Collection point delivery

{
  "timestamp": "2025-05-16T10:00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Delivery request flagged for fraud",
  "path": "/api/v1/deliveries"
}

• 400 Bad Request: Invalid input data or fraud detection
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server processing error

// Create delivery example
const response = await fetch('/api/v1/deliveries', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 'ORD-12345',
    destinationType: 'HOME',
    recipient: {
      name: 'John Doe',
      phone: '+1234567890',
      email: '[email protected]'
    }
  })
});

const delivery = await response.json();

try {
  const response = await fetch('/api/v1/deliveries/ORD-12345');
  
  if (!response.ok) {
    if (response.status === 404) {
      console.log('Delivery not found');
    } else if (response.status === 400) {
      console.log('Invalid request');
    }
    return;
  }
  
  const delivery = await response.json();
  // Process delivery data
} catch (error) {
  console.error('Network error:', error);
}

• CORS configuration should be added for cross-origin requests
• Consider allowing specific origins in production

cors:
  allowed-origins: 
    - "http://localhost:3000"
    - "https://yourdomain.com"
  allowed-methods: GET,POST,PUT,PATCH,DELETE,OPTIONS
  allowed-headers: "*"

• Redis Integration: Configured but implementation needed
• HTTP Caching: Consider adding cache headers for GET requests
• Database Queries: Optimized with proper indexing

• Currently not implemented
• Recommended for production use
• Consider per-IP or per-user limits

• Not currently implemented
• Recommended for large datasets
• Standard format: ?page=1&size=20

// Example: Publishing delivery events
@EventListener
public void handleDeliveryCreated(DeliveryCreatedEvent event) {
    kafkaTemplate.send("delivery-events", event);
}

• delivery-events: Delivery lifecycle events
• fraud-alerts: Fraud detection notifications

Create Delivery Test:

curl -X POST http://localhost:8080/api/v1/deliveries \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "TEST-001",
    "destinationType": "HOME",
    "recipient": {
      "name": "Test User",
      "phone": "+1234567890",
      "email": "[email protected]"
    }
  }'

Get Delivery Test:

curl http://localhost:8080/api/v1/deliveries/TEST-001

1. Authentication & Authorization: JWT-based security
2. Real-time Updates: WebSocket support for status changes
3. Bulk Operations: Batch create/update endpoints
4. Advanced Filtering: More query parameters
5. File Upload: Support for delivery documents
6. Audit Trail: Track all changes
7. GraphQL Support: Alternative API format

• Swagger/OpenAPI: Auto-generated documentation
• Postman Collection: Pre-configured API calls
• Example Requests: Sample integration code

• H2 Console: Available in development mode
• Actuator Endpoints: Health checks and metrics
• Debug Logging: Configurable log levels

• API Documentation: [Swagger/OpenAPI URL]
• Support Team: [support-email]
• Issue Tracking: [JIRA/GitHub URL]
• API Changes: [changelog-url]