API Documentation

Complete REST API reference for all microservices

API Gateway

All APIs are accessed through the API Gateway at http://localhost:8080

Base URL: http://localhost:8080

Content-Type: application/json

All requests are routed through Spring Cloud Gateway

Customer Service APIs

Manage customer profiles and addresses

POST /api/v1/customers

Create a new customer

Request Body:

JSON 
{
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "address": {
    "street": "Main Street",
    "houseNumber": "123",
    "zipCode": "12345"
  }
}

Response (201 Created):

{
  "id": "65f4a1b2c3d4e5f6a7b8c9d0",
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "address": {
    "street": "Main Street",
    "houseNumber": "123",
    "zipCode": "12345"
  }
}

cURL Example:

curl -X POST http://localhost:8080/api/v1/customers \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "Main Street",
      "houseNumber": "123",
      "zipCode": "12345"
    }
  }'
GET /api/v1/customers

Get all customers

Response (200 OK):

[
  {
    "id": "65f4a1b2c3d4e5f6a7b8c9d0",
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "Main Street",
      "houseNumber": "123",
      "zipCode": "12345"
    }
  }
]
GET /api/v1/customers/{id}

Get customer by ID

GET /api/v1/customers/exists/{id}

Check if customer exists

Response (200 OK):

true

Product Service APIs

Browse products and manage inventory

GET /api/v1/products

Get all products

Response (200 OK):

[
  {
    "id": 1,
    "name": "Mechanical Gaming Keyboard",
    "description": "RGB backlit mechanical keyboard with Cherry MX switches",
    "availableQuantity": 50.0,
    "price": 129.99,
    "categoryId": 1,
    "categoryName": "Keyboards",
    "categoryDescription": "Computer Keyboards"
  }
]

cURL Example:

curl http://localhost:8080/api/v1/products
GET /api/v1/products/{id}

Get product by ID

POST /api/v1/products/purchase

Purchase products (reduce inventory)

Request Body:

[
  {
    "productId": 1,
    "quantity": 2
  },
  {
    "productId": 2,
    "quantity": 1
  }
]

Response (200 OK):

[
  {
    "productId": 1,
    "name": "Mechanical Gaming Keyboard",
    "description": "RGB backlit mechanical keyboard",
    "price": 129.99,
    "quantity": 2
  }
]

Order Service APIs

Place and manage orders

POST /api/v1/orders

Create a new order

This endpoint orchestrates the complete order flow: validates customer, purchases products, processes payment, and sends notifications via Kafka

Request Body:

JSON 
{
  "customerId": "65f4a1b2c3d4e5f6a7b8c9d0",
  "paymentMethod": "CREDIT_CARD",
  "products": [
    {
      "productId": 1,
      "quantity": 2
    },
    {
      "productId": 5,
      "quantity": 1
    }
  ]
}

Payment Methods:

  • CREDIT_CARD
  • DEBIT_CARD
  • PAYPAL
  • UPI

Response (201 Created):

{
  "id": 1,
  "reference": "ORD-2024-001",
  "totalAmount": 389.97,
  "paymentMethod": "CREDIT_CARD",
  "customerId": "65f4a1b2c3d4e5f6a7b8c9d0"
}

Complete cURL Example:

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "65f4a1b2c3d4e5f6a7b8c9d0",
    "paymentMethod": "CREDIT_CARD",
    "products": [
      {
        "productId": 1,
        "quantity": 2
      }
    ]
  }'

After successful order creation, you'll receive order confirmation and payment confirmation emails in MailDev (http://localhost:1080)

GET /api/v1/orders/{id}

Get order by ID

Payment Service

Payment processing is handled automatically by the Order Service. No direct API calls needed.

The Payment Service is called internally by the Order Service via OpenFeign. It publishes payment confirmation events to Kafka.

Notification Service

Notifications are sent automatically via Kafka events. No direct API calls needed.

The Notification Service consumes Kafka events and sends HTML emails. Check MailDev at http://localhost:1080 to view sent emails.

Monitoring & Discovery

Eureka Dashboard

http://localhost:8082

View all registered services

Zipkin Tracing

http://localhost:9411

Distributed request tracing

Health Checks

/actuator/health

Check service health

MailDev

http://localhost:1080

Email testing interface

Health Check Examples

Check Customer Service Health 
curl http://localhost:8081/actuator/health
Check Gateway Health 
curl http://localhost:8080/actuator/health

Error Responses

400 Bad Request

Invalid request body or missing required fields

{
  "timestamp": "2024-03-15T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/customers"
}

404 Not Found

Resource not found

{
  "timestamp": "2024-03-15T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Customer not found with id: 123",
  "path": "/api/v1/customers/123"
}

500 Internal Server Error

Server error occurred

{
  "timestamp": "2024-03-15T10:30:00",
  "status": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "path": "/api/v1/orders"
}

Complete E2E Workflow

Step-by-step example of creating a complete order

1

Create a Customer

curl -X POST http://localhost:8080/api/v1/customers \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jane",
    "lastname": "Smith",
    "email": "jane.smith@example.com",
    "address": {
      "street": "Oak Avenue",
      "houseNumber": "456",
      "zipCode": "67890"
    }
  }'

Save the returned customer ID for the next step

2

Browse Products

curl http://localhost:8080/api/v1/products

Note the product IDs you want to order

3

Place an Order

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "YOUR_CUSTOMER_ID_HERE",
    "paymentMethod": "CREDIT_CARD",
    "products": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 5,
        "quantity": 1
      }
    ]
  }'
4

Check Notifications

Open MailDev to see the order and payment confirmation emails:

Open MailDev
5

View Traces in Zipkin

See the complete distributed trace of your order:

Open Zipkin