Skip to content

API_DOCS.md

Latest commit

 

History

History
275 lines (231 loc) · 5.11 KB

API_DOCS.md

File metadata and controls

275 lines (231 loc) · 5.11 KB

CRUD API Documentation

Base URL

http://localhost:8001

Authentication

This API does not require authentication for demo purposes.

Response Format

All API responses follow this structure:

Success Response

{
  "success": true,
  "data": { /* response data */ },
  "message": "Operation completed successfully",
  "timestamp": "2025-06-23T19:32:49.982Z"
}

Error Response

{
  "error": "Error Type",
  "message": "Detailed error message",
  "timestamp": "2025-06-23T19:32:49.982Z"
}

Endpoints

Method Endpoint Description Parameters
GET /health Health check None
GET /api/items Get all items None
GET /api/items/:id Get item by ID id (integer)
POST /api/items Create new item Request body
PUT /api/items/:id Update item by ID id (integer), Request body
DELETE /api/items/:id Delete item by ID id (integer)

GET /health

Health check endpoint to verify server status.

Request:

curl -X GET http://localhost:8001/health

Response (200 OK):

{
  "status": "OK",
  "timestamp": "2025-06-23T19:32:38.497Z",
  "uptime": 19.959816079
}

GET /api/items

Retrieve all items in descending order by creation date.

Request:

curl -X GET http://localhost:8001/api/items

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Sample Item",
      "value": 100,
      "createdAt": "2025-06-23T19:32:49.965Z",
      "updatedAt": "2025-06-23T19:32:49.965Z"
    }
  ],
  "count": 1,
  "timestamp": "2025-06-23T19:32:44.008Z"
}

GET /api/items/:id

Retrieve a specific item by its ID.

Request:

curl -X GET http://localhost:8001/api/items/1

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Sample Item",
    "value": 100,
    "createdAt": "2025-06-23T19:32:49.965Z",
    "updatedAt": "2025-06-23T19:32:49.965Z"
  },
  "timestamp": "2025-06-23T19:32:55.327Z"
}

Response (404 Not Found):

{
  "error": "Not Found",
  "message": "Item with id 999 not found",
  "timestamp": "2025-06-23T19:32:55.327Z"
}

POST /api/items

Create a new item.

Request Body Schema:

{
  "name": "string (required, 1-255 characters)",
  "value": "integer (required, >= 0)"
}

Request:

curl -X POST http://localhost:8001/api/items \
  -H "Content-Type: application/json" \
  -d '{"name": "New Item", "value": 200}'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 2,
    "name": "New Item",
    "value": 200,
    "createdAt": "2025-06-23T19:32:49.965Z",
    "updatedAt": "2025-06-23T19:32:49.965Z"
  },
  "message": "Item created successfully",
  "timestamp": "2025-06-23T19:32:49.982Z"
}

Response (400 Bad Request):

{
  "error": "Validation Error",
  "message": "Name is required, Value must be a positive integer",
  "details": [
    {
      "msg": "Name is required",
      "param": "name",
      "location": "body"
    }
  ],
  "timestamp": "2025-06-23T19:32:49.982Z"
}

PUT /api/items/:id

Update an existing item. Only provided fields will be updated.

Request Body Schema:

{
  "name": "string (optional, 1-255 characters)",
  "value": "integer (optional, >= 0)"
}

Request:

curl -X PUT http://localhost:8001/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Item", "value": 300}'

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Updated Item",
    "value": 300,
    "createdAt": "2025-06-23T19:32:49.965Z",
    "updatedAt": "2025-06-23T19:33:00.251Z"
  },
  "message": "Item updated successfully",
  "timestamp": "2025-06-23T19:33:00.260Z"
}

Response (404 Not Found):

{
  "error": "Not Found",
  "message": "Item with id 999 not found",
  "timestamp": "2025-06-23T19:33:00.260Z"
}

DELETE /api/items/:id

Delete an item by its ID.

Request:

curl -X DELETE http://localhost:8001/api/items/1

Response (200 OK):

{
  "success": true,
  "message": "Item deleted successfully",
  "data": {
    "id": 1
  },
  "timestamp": "2025-06-23T19:33:05.123Z"
}

Response (404 Not Found):

{
  "error": "Not Found",
  "message": "Item with id 999 not found",
  "timestamp": "2025-06-23T19:33:05.123Z"
}

Status Codes

Code Description
200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Invalid request data
404 Not Found - Resource not found
409 Conflict - Resource already exists
500 Internal Server Error - Server error

Error Handling

The API includes comprehensive error handling for:

  • Validation Errors: Invalid input data, missing required fields
  • Not Found Errors: Requesting non-existent resources
  • Database Errors: Connection issues, constraint violations
  • Server Errors: Unexpected server errors

All errors include descriptive messages and appropriate HTTP status codes.