[Auto] Write API documentation and usage guide

.bass/issue.md

@@ -0,0 +1,14 @@
+# Write API documentation and usage guide
+
+Document the API in the project README or an API.md file. Include endpoint descriptions, request/response examples, error response formats, and instructions for running the server and tests locally.
+
+Acceptance Criteria:
+- Every endpoint has a description, method, path, parameters, and example request/response
+- Setup and test instructions are clear and accurate
+- Error response format is documented
+
+Test Cases:
+- Docs review: A reviewer can follow the README to install dependencies, run the server, and execute all tests successfully
+- Docs review: All example curl commands in the docs produce the documented responses against a running server
+
+Please implement this fix.

README.md

@@ -0,0 +1,299 @@
+# Todo API Server
+
+A lightweight REST API for managing personal todo items, built with Express.js.
+
+## Quick Start
+
+```bash
+npm install
+npm start
+```
+
+The server runs on `http://localhost:3000` by default. Change the port with `PORT`:
+
+```bash
+PORT=8080 npm start
+```
+
+## API Endpoints
+
+All endpoints use `application/json`. The base URL is `http://localhost:3000`.
+
+### Todo Object
+
+| Field       | Type    | Description                    |
+|-------------|---------|--------------------------------|
+| id          | string  | UUID, auto-generated           |
+| title       | string  | Task description               |
+| completed   | boolean | Default `false`                |
+| createdAt   | string  | ISO 8601 creation timestamp    |
+| updatedAt   | string  | ISO 8601 last update timestamp |
+
+---
+
+### Create a Todo
+
+```
+POST /todos
+```
+
+**Request Body**
+
+| Field | Type   | Required | Description              |
+|-------|--------|----------|--------------------------|
+| title | string | Yes      | Non-empty task title     |
+
+**Example**
+
+```bash
+curl -X POST http://localhost:3000/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Buy groceries"}'
+```
+
+**Response: `201 Created`**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "title": "Buy groceries",
+  "completed": false,
+  "createdAt": "2026-04-17T16:20:04.603Z",
+  "updatedAt": "2026-04-17T16:20:04.603Z"
+}
+```
+
+---
+
+### List Todos
+
+```
+GET /todos
+```
+
+**Query Parameters**
+
+| Parameter   | Type    | Required | Description                          |
+|-------------|---------|----------|--------------------------------------|
+| completed   | boolean | No       | Filter by completion status          |
+
+**Examples**
+
+```bash
+# All todos
+curl http://localhost:3000/todos
+
+# Only completed
+curl "http://localhost:3000/todos?completed=true"
+
+# Only incomplete
+curl "http://localhost:3000/todos?completed=false"
+```
+
+**Response: `200 OK`**
+
+```json
+[
+  {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "title": "Buy groceries",
+    "completed": false,
+    "createdAt": "2026-04-17T16:20:04.603Z",
+    "updatedAt": "2026-04-17T16:20:04.603Z"
+  },
+  {
+    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "title": "Write report",
+    "completed": true,
+    "createdAt": "2026-04-17T16:20:05.100Z",
+    "updatedAt": "2026-04-17T16:20:10.200Z"
+  }
+]
+```
+
+---
+
+### Get a Todo
+
+```
+GET /todos/:id
+```
+
+**Path Parameters**
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| id        | string | Yes      | Todo UUID   |
+
+**Example**
+
+```bash
+curl http://localhost:3000/todos/a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+**Response: `200 OK`**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "title": "Buy groceries",
+  "completed": false,
+  "createdAt": "2026-04-17T16:20:04.603Z",
+  "updatedAt": "2026-04-17T16:20:04.603Z"
+}
+```
+
+**Response: `404 Not Found`**
+
+```json
+{
+  "error": "Todo not found"
+}
+```
+
+---
+
+### Update a Todo
+
+```
+PATCH /todos/:id
+```
+
+**Path Parameters**
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| id        | string | Yes      | Todo UUID   |
+
+**Request Body** (at least one field required)
+
+| Field     | Type    | Required | Description              |
+|-----------|---------|----------|--------------------------|
+| title     | string  | No       | New task title           |
+| completed | boolean | No       | New completion status    |
+
+**Example**
+
+```bash
+curl -X PATCH http://localhost:3000/todos/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
+  -H "Content-Type: application/json" \
+  -d '{"completed": true}'
+```
+
+**Response: `200 OK`**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "title": "Buy groceries",
+  "completed": true,
+  "createdAt": "2026-04-17T16:20:04.603Z",
+  "updatedAt": "2026-04-17T16:20:10.200Z"
+}
+```
+
+**Response: `400 Bad Request`** (no fields provided)
+
+```json
+{
+  "error": "At least one of title or completed must be provided"
+}
+```
+
+**Response: `400 Bad Request`** (invalid field type)
+
+```json
+{
+  "error": "title must be a non-empty string"
+}
+```
+
+---
+
+### Delete a Todo
+
+```
+DELETE /todos/:id
+```
+
+**Path Parameters**
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| id        | string | Yes      | Todo UUID   |
+
+**Example**
+
+```bash
+curl -X DELETE http://localhost:3000/todos/a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+**Response: `204 No Content`**
+
+No response body.
+
+**Response: `404 Not Found`**
+
+```json
+{
+  "error": "Todo not found"
+}
+```
+
+## Error Responses
+
+All errors return a JSON object with an `error` field:
+
+```json
+{
+  "error": "Human-readable error message"
+}
+```
+
+| Status Code | Meaning                              |
+|-------------|--------------------------------------|
+| 400         | Request validation failed            |
+| 404         | Todo with the given ID not found     |
+
+## Testing
+
+The current test script is a placeholder. To manually test all endpoints:
+
+```bash
+# 1. Start the server
+npm start &
+
+# 2. Create a todo
+TODO=$(curl -s -X POST http://localhost:3000/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Test todo"}')
+ID=$(echo "$TODO" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+
+# 3. List todos
+curl http://localhost:3000/todos
+
+# 4. Get the todo
+curl http://localhost:3000/todos/$ID
+
+# 5. Update the todo
+curl -X PATCH http://localhost:3000/todos/$ID \
+  -H "Content-Type: application/json" \
+  -d '{"completed": true}'
+
+# 6. Filter completed todos
+curl "http://localhost:3000/todos?completed=true"
+
+# 7. Delete the todo
+curl -X DELETE http://localhost:3000/todos/$ID
+
+# 8. Verify deletion (should return 404)
+curl http://localhost:3000/todos/$ID
+
+# 9. Stop the server
+kill %1
+```
+
+## Notes
+
+- Data is stored in memory and is lost when the server stops.
+- No authentication is required.