apirestful/API_REFERENCE.md

API Endpoints Reference

Base URL

http://localhost:8080

Documentation & Console

Resource	URL	Description
Swagger UI	http://localhost:8080/swagger-ui.html	Interactive API documentation
OpenAPI JSON	http://localhost:8080/v3/api-docs	OpenAPI specification
H2 Console	http://localhost:8080/h2-console	Database console

Customer API Endpoints

1. Get All Customers

GET /api/customers

Response: 200 OK

[
  {
    "id": 1,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main St",
    "createdAt": "2025-12-13T10:30:00",
    "updatedAt": "2025-12-13T10:30:00"
  }
]

cURL:

curl http://localhost:8080/api/customers

---

2. Get Customer by ID

GET /api/customers/{id}

Parameters:

• id (path, required): Customer ID

Response: 200 OK

{
  "id": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "address": "123 Main St",
  "createdAt": "2025-12-13T10:30:00",
  "updatedAt": "2025-12-13T10:30:00"
}

Errors:

• 404 Not Found - Customer not found

cURL:

curl http://localhost:8080/api/customers/1

---

3. Create Customer

POST /api/customers
Content-Type: application/json

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "address": "123 Main St, City, Country"
}

Validation Rules:

• firstName: Required, max 100 characters
• lastName: Required, max 100 characters
• email: Required, valid email format, unique, max 150 characters
• phone: Optional, max 20 characters
• address: Optional, max 255 characters

Response: 201 Created

{
  "id": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "address": "123 Main St, City, Country",
  "createdAt": "2025-12-13T10:30:00",
  "updatedAt": "2025-12-13T10:30:00"
}

Errors:

• 400 Bad Request - Validation failed
• 409 Conflict - Email already exists

cURL:

curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main St, City"
  }'

---

4. Update Customer

PUT /api/customers/{id}
Content-Type: application/json

Parameters:

• id (path, required): Customer ID

Request Body:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+0987654321",
  "address": "456 Oak Ave, City"
}

Response: 200 OK

{
  "id": 1,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+0987654321",
  "address": "456 Oak Ave, City",
  "createdAt": "2025-12-13T10:30:00",
  "updatedAt": "2025-12-13T11:45:00"
}

Errors:

• 400 Bad Request - Validation failed
• 404 Not Found - Customer not found
• 409 Conflict - Email already exists (if changed)

cURL:

curl -X PUT http://localhost:8080/api/customers/1 \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+0987654321",
    "address": "456 Oak Ave"
  }'

---

5. Delete Customer

DELETE /api/customers/{id}

Parameters:

• id (path, required): Customer ID

Response: 204 No Content

Errors:

• 404 Not Found - Customer not found

cURL:

curl -X DELETE http://localhost:8080/api/customers/1

---

Error Responses

400 Bad Request (Validation Error)

{
  "status": 400,
  "errors": {
    "firstName": "First name is required",
    "email": "Email must be valid"
  },
  "timestamp": "2025-12-13T10:30:00"
}

404 Not Found

{
  "status": 404,
  "message": "Customer not found with id: 999",
  "timestamp": "2025-12-13T10:30:00"
}

409 Conflict (Duplicate Email)

{
  "status": 409,
  "message": "Email already exists: john.doe@example.com",
  "timestamp": "2025-12-13T10:30:00"
}

500 Internal Server Error

{
  "status": 500,
  "message": "An unexpected error occurred",
  "timestamp": "2025-12-13T10:30:00"
}

---

Testing with cURL - Complete Example

# 1. Create first customer
curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"firstName":"John","lastName":"Doe","email":"john@example.com","phone":"+1234567890","address":"123 Main St"}'

# 2. Create second customer
curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Smith","email":"jane@example.com","phone":"+0987654321","address":"456 Oak Ave"}'

# 3. Get all customers
curl http://localhost:8080/api/customers

# 4. Get customer by ID
curl http://localhost:8080/api/customers/1

# 5. Update customer
curl -X PUT http://localhost:8080/api/customers/1 \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Johnny","lastName":"Doe","email":"johnny@example.com","phone":"+1111111111","address":"789 New St"}'

# 6. Delete customer
curl -X DELETE http://localhost:8080/api/customers/2

# 7. Try to get deleted customer (should return 404)
curl http://localhost:8080/api/customers/2

# 8. Test validation error
curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"firstName":"","lastName":"Test","email":"invalid-email"}'

# 9. Test duplicate email error
curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Test","lastName":"User","email":"johnny@example.com","phone":"123","address":"test"}'

---

Response Headers

All responses include standard headers:

• Content-Type: application/json
• Date: <timestamp>
• Transfer-Encoding: chunked

---

Notes

• All operations are asynchronous using Spring's @Async
• Email field has a unique constraint in the database
• Timestamps are automatically managed (createdAt, updatedAt)
• All endpoints are accessible without authentication (development mode)
• Use Swagger UI for interactive testing: http://localhost:8080/swagger-ui.html