TaskService/API_REFERENCE.md

Task Service API Quick Reference

Base URL

http://localhost:8082

Authentication

All endpoints (except health check) require JWT authentication in the header:

Authorization: Bearer <your_jwt_token>

---

Endpoints Summary

Method	Endpoint	Description	Auth	Admin Only
GET	/tasks	Health check	No	No
POST	/api/tasks	Create task	Yes	Yes
GET	/api/tasks	Get all tasks	Yes	No
GET	/api/tasks/{id}	Get task by ID	Yes	No
GET	/api/tasks/user	Get user's assigned tasks	Yes	No
PUT	/api/tasks/{id}	Update task	Yes	No
PUT	/api/tasks/{id}/user/{userId}/assigned	Assign task to user	Yes	No
PUT	/api/tasks/{id}/complete	Mark task as complete	Yes	No
DELETE	/api/tasks/{id}	Delete task	Yes	No

---

Detailed API Documentation

1. Health Check

Check if service is running.

Request:

GET /tasks

Response:

"Welcome to Task Service"

---

2. Create Task (Admin Only)

Create a new task. Only users with ROLE_ADMIN can create tasks.

Request:

POST /api/tasks
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "title": "Implement new feature",
  "description": "Implement the new authentication feature",
  "imageUrl": "https://example.com/image.png",
  "deadline": "2024-12-31T23:59:59",
  "tags": ["backend", "security", "priority-high"]
}

Response (201 CREATED):

{
  "id": "65f9a1234567890abcdef123",
  "title": "Implement new feature",
  "description": "Implement the new authentication feature",
  "imageUrl": "https://example.com/image.png",
  "assignedUserId": null,
  "status": "PENDING",
  "deadline": "2024-12-31T23:59:59",
  "createAt": "2024-11-10T10:30:00",
  "tags": ["backend", "security", "priority-high"]
}

---

3. Get All Tasks

Retrieve all tasks with optional filtering and sorting.

Request:

GET /api/tasks?status=PENDING&sortByDeadline=asc
Authorization: Bearer <jwt_token>

Query Parameters:

• status (optional): Filter by status - PENDING, ASSIGNED, or DONE
• sortByDeadline (optional): Sort by deadline - asc or desc
• sortByCreatedAt (optional): Sort by creation date - asc or desc

Response (200 OK):

[
  {
    "id": "65f9a1234567890abcdef123",
    "title": "Implement new feature",
    "description": "Implement the new authentication feature",
    "imageUrl": "https://example.com/image.png",
    "assignedUserId": null,
    "status": "PENDING",
    "deadline": "2024-12-31T23:59:59",
    "createAt": "2024-11-10T10:30:00",
    "tags": ["backend", "security"]
  },
  {
    "id": "65f9a1234567890abcdef456",
    "title": "Fix bug in payment module",
    "description": "Resolve the payment gateway timeout issue",
    "imageUrl": null,
    "assignedUserId": null,
    "status": "PENDING",
    "deadline": "2024-11-15T18:00:00",
    "createAt": "2024-11-10T11:00:00",
    "tags": ["bug", "payment"]
  }
]

---

4. Get Task by ID

Retrieve a specific task by its ID.

Request:

GET /api/tasks/65f9a1234567890abcdef123
Authorization: Bearer <jwt_token>

Response (200 OK):

{
  "id": "65f9a1234567890abcdef123",
  "title": "Implement new feature",
  "description": "Implement the new authentication feature",
  "imageUrl": "https://example.com/image.png",
  "assignedUserId": "user123",
  "status": "ASSIGNED",
  "deadline": "2024-12-31T23:59:59",
  "createAt": "2024-11-10T10:30:00",
  "tags": ["backend", "security"]
}

Error Response (404 NOT FOUND):

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "Task not found with id: 65f9a1234567890abcdef123",
  "status": 404,
  "error": "Task Not Found"
}

---

5. Get User's Assigned Tasks

Retrieve all tasks assigned to the authenticated user.

Request:

GET /api/tasks/user?status=ASSIGNED&sortByDeadline=asc
Authorization: Bearer <jwt_token>

Query Parameters:

• status (optional): Filter by status - PENDING, ASSIGNED, or DONE
• sortByDeadline (optional): Sort by deadline - asc or desc
• sortByCreatedAt (optional): Sort by creation date - asc or desc

Response (200 OK):

[
  {
    "id": "65f9a1234567890abcdef123",
    "title": "Implement new feature",
    "description": "Implement the new authentication feature",
    "imageUrl": "https://example.com/image.png",
    "assignedUserId": "user123",
    "status": "ASSIGNED",
    "deadline": "2024-12-31T23:59:59",
    "createAt": "2024-11-10T10:30:00",
    "tags": ["backend", "security"]
  }
]

---

6. Update Task

Update an existing task's information.

Request:

PUT /api/tasks/65f9a1234567890abcdef123
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "title": "Implement new feature (Updated)",
  "description": "Updated description",
  "status": "ASSIGNED",
  "deadline": "2024-12-25T23:59:59",
  "tags": ["backend", "security", "updated"]
}

Response (200 OK):

{
  "id": "65f9a1234567890abcdef123",
  "title": "Implement new feature (Updated)",
  "description": "Updated description",
  "imageUrl": "https://example.com/image.png",
  "assignedUserId": "user123",
  "status": "ASSIGNED",
  "deadline": "2024-12-25T23:59:59",
  "createAt": "2024-11-10T10:30:00",
  "tags": ["backend", "security", "updated"]
}

---

7. Assign Task to User

Assign a task to a specific user.

Request:

PUT /api/tasks/65f9a1234567890abcdef123/user/user456/assigned
Authorization: Bearer <jwt_token>

Response (200 OK):

{
  "id": "65f9a1234567890abcdef123",
  "title": "Implement new feature",
  "description": "Implement the new authentication feature",
  "imageUrl": "https://example.com/image.png",
  "assignedUserId": "user456",
  "status": "ASSIGNED",
  "deadline": "2024-12-31T23:59:59",
  "createAt": "2024-11-10T10:30:00",
  "tags": ["backend", "security"]
}

---

8. Complete Task

Mark a task as completed.

Request:

PUT /api/tasks/65f9a1234567890abcdef123/complete
Authorization: Bearer <jwt_token>

Response (200 OK):

{
  "id": "65f9a1234567890abcdef123",
  "title": "Implement new feature",
  "description": "Implement the new authentication feature",
  "imageUrl": "https://example.com/image.png",
  "assignedUserId": "user123",
  "status": "DONE",
  "deadline": "2024-12-31T23:59:59",
  "createAt": "2024-11-10T10:30:00",
  "tags": ["backend", "security"]
}

---

9. Delete Task

Delete a task by ID.

Request:

DELETE /api/tasks/65f9a1234567890abcdef123
Authorization: Bearer <jwt_token>

Response (204 NO CONTENT):

(No body returned)

---

Task Status Flow

PENDING → ASSIGNED → DONE

1. PENDING: Task created by admin, not assigned to anyone
2. ASSIGNED: Task assigned to a user
3. DONE: Task marked as completed

---

Common Error Responses

400 Bad Request

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "Invalid request parameters",
  "status": 400,
  "error": "Bad Request"
}

401 Unauthorized

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "JWT required...",
  "status": 401,
  "error": "Unauthorized"
}

403 Forbidden

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "Only admin can create tasks",
  "status": 403,
  "error": "Forbidden"
}

404 Not Found

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "Task not found with id: 65f9a1234567890abcdef123",
  "status": 404,
  "error": "Task Not Found"
}

500 Internal Server Error

{
  "timestamp": "2024-11-10T10:30:00",
  "message": "Internal server error",
  "status": 500,
  "error": "Internal Server Error"
}

---

Testing with cURL

Create Task (Admin)

curl -X POST http://localhost:8082/api/tasks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Task",
    "description": "This is a test task",
    "deadline": "2024-12-31T23:59:59",
    "tags": ["test"]
  }'

Get All Tasks

curl -X GET "http://localhost:8082/api/tasks?status=PENDING" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Task by ID

curl -X GET http://localhost:8082/api/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Task

curl -X PUT http://localhost:8082/api/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Task Title",
    "status": "ASSIGNED"
  }'

Complete Task

curl -X PUT http://localhost:8082/api/tasks/TASK_ID/complete \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete Task

curl -X DELETE http://localhost:8082/api/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Notes

• All timestamps are in ISO 8601 format
• Task IDs are MongoDB ObjectIds (24-character hexadecimal strings)
• JWT tokens must be obtained from the User Service authentication endpoint
• Only admin users can create tasks
• Tasks can be in one of three states: PENDING, ASSIGNED, or DONE
• Sorting can be applied to either deadline or creation date, but not both simultaneously