Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
1048 lines (898 loc) · 27 KB

API_DOCUMENTATION.md

File metadata and controls

1048 lines (898 loc) · 27 KB

API Documentation

This document provides an overview of the API endpoints available in the system. Each section corresponds to a controller and details the available routes, methods, parameters, and expected responses.

Introduction

Welcome to the Task Manager API. This API allows developers to manage admins, teams, tasks, and assignments within the system. It is designed to be RESTful, using standard HTTP methods and response codes.

A REST API allows different systems to communicate over the internet using standard HTTP methods. Each request interacts with the API's resources, such as "admins" and "tasks".

Base URL

All API requests should be made to the following base URL (Spring Boot's default settings): http://localhost:8080

Table of Contents

  1. AdminAccountController
  2. AdminController
  3. AuthInfoController
  4. IsAssignedController
  5. IsMemberOfController
  6. TaskController
  7. TeamController
  8. TeamMemberAccountController
  9. TeamMemberController
  10. NotificationController
  11. Path Variables
  12. DTO References
  13. Request and Response Examples
  14. Best Practices
  15. Error Codes
  16. Example Error Response

AdminAccountController

Base URL: /api/admins

Endpoints

  • Create Admin: POST /

    • Request Body:
    {
    "name": "Admin Name",
    "email": "admin@example.com",
    "password": "securepassword"
}
    • Response Body:
    {
    "accountId": 1,
    "userName": "Admin Name",
    "userEmail": "admin@example.com"
}
    • Description: Creates a new admin in the system.

  • Delete Admin: DELETE /{adminId}

    • Parameters:
      • adminId (integer, required): The unique ID of the admin to be deleted.
    • Description: Removes an admin from the system permanently.

  • Modify Admin Name: PUT /{adminId}/name

    • Request Body:
    {
    "newName": "Updated Admin Name"
}
    • Response Body:
    {
    "accountId": 1,
    "userName": "Updated Admin Name",
    "userEmail": "admin@example.com"
}
    • Description: Updates the admin's name field in the database.

  • Modify Admin Email: PUT /{adminId}/email

    • Request Body:
    {
    "newEmail": "updated.admin@example.com"
}
    • Response Body:
    {
    "accountId": 1,
    "userName": "Admin Name",
    "userEmail": "updated.admin@example.com"
}
    • Description: Updates the admin's email field in the database.

  • Get Admin by ID GET /{adminId}

    • Parameters:
      • adminId (integer, required): The ID of the admin being retrieved.
    • Response Body:
    {
    "accountId": 1,
    "userName": "Admin Name",
    "userEmail": "admin@example.com"
}
    • Description: Returns the id, name, and email of the requested admin.

AdminController

Base URL: /api/admins/actions

Endpoints

  • Assign Team Member to a Team: POST /team-member/{teamMemberId}/assign-to-team/{teamId}

    • Parameters:
      • teamMemberId (integer, required): The ID of the team member to assign.
      • teamId (integer, required): The ID of the team to assign them to.
    • Description: Assigns a team member to a specified team.

  • Change Role: POST /{teamMemberId}/role

    • Parameters:
      • teamMemberId (integer, required): The ID of the member having their role changed.
    • Request Body:
    {
    "role": "ADMIN"
}
    • Response Body:
    {
    "accountId": 1,
    "userName": "Name",
    "userEmail": "email@example.com",
    "role": "ADMIN"
}
    • Note: The member's ID will change, provide them with the new one.

  • Lock a Task: PUT /tasks/{taskId}/lock

    • Parameters:
      • taskId (integer, required): The ID of the task to lock.
    • Description: Locks a task to prevent any modifications. Once locked, updates and deletions are restricted.

  • Unlock a Task: PUT /tasks/{taskId}/unlock

    • Parameters:
      • taskId (integer, required): The ID of the task to unlock.
    • Description: Unlocks a task, allowing updates and modifications.

  • Get All Admins: GET

    • Response Body:
    [
    {
        "accountId": 1,
        "userName": "Admin Name",
        "userEmail": "admin@example.com"
    },
    {
        "accountId": 2,
        "userName": "Admin 2",
        "userEmail": "admin_2@example.com"
    }
]
    • Description: Returns a list of every admin in the database.

  • Reset Password: POST /{teamMemberId}/reset-password

    • Request Body:
    {
    "newPassword": "newPassword"
}
    • Description: Updates the password field for a team member without providing the old password.

AuthInfoController

Base URL: /api/auth

Endpoints

  • Login: POST /login

    • Request Body:
    {
    "teamMemberId": 1,
    "password": "password"
}
    • Response Body:
    {
    "id": 1,
    "name": "Test User",
    "role": "TEAM_MEMBER"
}
    • Description: Logs a user in.

  • IsAdmin: POST /{teamMemberId}/is-admin

    • Request Body:
    {
    "teamMemberId": 1
}
    • Response Body:
    {
    "role": "TEAM_MEMBER"
}
    • Response Body:
    {
    "adminId": 2
}
    • Response Body:
    {
    "role": "ADMIN"
}
    • Description: Checks if a user is an admin.

IsAssignedController

Base URL: /api/assignments

Endpoints

  • Assign a Team Member to a Task: POST /{teamMemberId}/task/{taskId}

    • Description: Assigns a team member to a task.

  • Unassign a Team Member from a Task: DELETE /{teamMemberId}/task/{taskId}

    • Description: Unassigns a team member from a task.

  • Check if Assigned: GET /{teamMemberId}/task/{taskId}

    • Description: Returns a boolean of whether a team member is currently assigned to a task.

IsMemberOfController

Base URL: /api/memberships

Endpoints

  • Add a Member to a Team: POST /{teamMemberId}/team/{teamId}

    • Description: Adds a team member to a team.

  • Mass Assign to a Team: POST /team/{teamId}/mass-assign

    • Request Body:
        [1, 2, 3, 4]
    • Response Body:
    [
    {
        "isMemberOfId": 101,
        "teamMemberId": 1,
        "teamId": 42
    },
    {
        "isMemberOfId": 102,
        "teamMemberId": 2,
        "teamId": 42
    },
    {
        "isMemberOfId": 103,
        "teamMemberId": 3,
        "teamId": 42
    }
]
    • Description: Adds multiple members to a team at once. If any member is already in the team they will be skipped. If any member does not exist, the entire request will fail with a 400 error.

  • Remove a Member from a Team: DELETE /{teamMemberId}/team/{teamId}

    • Description: Removes a team member from a team.

  • Check if a Member is assigned to a Team: GET /{teamMemberId}/team/{teamId}

    • Description: Returns a boolean of whether a team member is assigned to a team.

TaskController

Base URL: /api/tasks

Endpoints

  • Create a Task: POST

    • Request Body:
    {
    "title": "Task Title",
    "description": "Task Description",
    "isLocked": false,
    "status": "To-Do",
    "dueDate": "2025-03-01",
    "teamId": 3,
    "priority": "HIGH"
}
    • Response Body:
    {
    "taskId": 4,
    "title": "Task Title",
    "description": "Task Description",
    "isLocked": false,
    "status": "To-Do",
    "dueDate": "2025-03-01",
    "teamId": 3,
    "priority": "HIGH"
}
    • Description: Creates a task in the database.

  • Delete a Task: DELETE /{taskId}

    • Description: Deletes a task from the database.

  • Edit a Task: PUT /{taskId}

    • Request Body: (TaskDTO, JSON)
    {
    "title": "Updated Title",
    "description": "Updated Description",
    "isLocked": false,
    "status": "In Progress",
    "dueDate": "2025-04-01",
    "priority": "HIGH"
}
    • Response Body:
    {
    "taskId": 4,
    "title": "Updated Title",
    "description": "Updated Description",
    "isLocked": false,
    "status": "In Progress",
    "dueDate": "2025-04-01",
    "teamId": 3,
    "priority": "HIGH"
}
    • Description: Updates the details of a task.

TeamController

Base URL: /api/teams

Endpoints

  • Create a Team: POST

    • Request Body:
    {
"teamId": 1,
"teamName": "Development Team",
"teamLeadId": 1001
}
    • Response Body:
    {
"teamId": 1,
"teamName": "Development Team",
"teamLeadId": 1001
}
    • Description: Creates a team in the database.

  • Delete a Team: DELETE /{teamId}

    • Description: Deletes a team from the database.

  • Change Team Lead: PUT /{teamId}/change-lead

    • Request Body:
    {
    "teamId": 1,
    "teamName": "Updated Team Name",
    "teamLeadId": 1002
}
    • Response Body:
    {
    "teamId": 1,
    "teamName": "Updated Team Name",
    "teamLeadId": 1002
}
    • Description: Updates the team lead for a specified team by assigning a different team member.

  • Get All Teams: GET

    • Response Body:
    [
    {
        "teamId": 1,
        "teamName": "Development Team"
    },
    {
        "teamId": 2,
        "teamName": "Marketing Team"
    }
]
    • Description: Returns a list of every team in the database.

  • Get Team Members: GET /{teamId}/members

    • Response Body:
        [
    {
        "accountId": 1,
        "userName": "John Doe",
        "userEmail": "john@example.com",
        "role": "ADMIN",
        "isTeamLead": true
    },
    {
        "accountId": 2,
        "userName": "Jane Smith",
        "userEmail": "jane@example.com",
        "role": "TEAM_MEMBER",
        "isTeamLead": false
    }
    ]
    • Description: Returns a list of every team member in a team. Each list item contains the team member's ID, name, email, role, and a boolean of whether they are the team lead.

  • Get Team Tasks: GET /{teamId}/tasks

    • Response Body:
    [
    {
        "taskId": 1,
        "title": "Task 1 title",
        "description": "Task 1 description.",
        "isLocked": false,
        "status": "Open",
        "dateCreated": "2025-03-24",
        "dueDate": null,
        "teamId": 2,
        "assignedMembers": 
        [
            {
                "accountId": 3,
                "userName": "Team Member name",
                "userEmail": "team_member@example.com",
                "role": "TEAM_MEMBER"
            }
        ]
    },
    {
        "taskId": 4,
        "title": "Task 2 title",
        "description": "Task 2 description.",
        "isLocked": false,
        "status": "To-Do",
        "dateCreated": "2025-03-24",
        "dueDate": "2025-04-01",
        "teamId": 2,
        "assignedMembers": []
    }
]
    • Description: Returns a list of tasks connected to the team through the team members.

TeamMemberAccountController

Base URL: /api/members

Endpoints

  • Create Team Member: POST

    • Request Body:
    {
    "name": "Team Member",
    "email": "teammember@example.com",
    "password": "securepassword"
}
    • Response Body:
    {
    "accountId": 2,
    "userName": "Team Member",
    "userEmail": "teammember@example.com"
}
    • Description: Adds a new team member to the system.

  • Delete Team Member: DELETE /{teamMemberId}

    • Parameters:
      • teamMemberId (integer, required): The unique ID of the team member to be deleted.
    • Description: Removes a team member from the system permanently.

  • Modify Team Member Name: PUT /{teamMemberId}/name

    • Request Body:
    {
    "newName": "Updated Team Member"
}
    • Response Body:
    {
    "accountId": 2,
    "userName": "Updated Team Member",
    "userEmail": "teammember@example.com"
}
    • Description: Updates the name field of the specified team member in the database.

  • Modify Team Member Email: PUT /{teamMemberId}/email

    • Request Body:
    {
    "newEmail": "updated.tm@example.com"
}
    • Response Body:
    {
    "accountId": 2,
    "userName": "Team Member",
    "userEmail": "updated.tm@example.com"
}
    • Description: Updates the email field of the specified team member in the database.

  • Get Team Member by ID GET /{teamMemberId}

    • Parameters:
      • teamMemberId (integer, required): The ID of the team member being retrieved.
    • Response Body:
    {
    "accountId": 1,
    "userName": "Team Member Name",
    "userEmail": "teamMember@example.com"
}
    • Description: Returns the id, name, and email of the requested team member.

  • Get All Team Members: GET

    • Response Body:
    [
    {
        "accountId": 2,
        "userName": "Team Member",
        "userEmail": "teammember@example.com",
        "role": "TEAM_MEMBER",
        "teamLead": true,
        "teamLeadOfId": [1, 2],
        "teamLeadOfName": ["Team One", "Team Two"]
    },
    {
        "accountId": 3,
        "userName": "Team Member3",
        "userEmail": "teammember3@example.com",
        "role": "ADMIN",
        "teamLead": false,
        "teamLeadOfId": [],
        "teamLeadOfName": []
    }
]
    • Description: Returns a list of every team member in the database.

TeamMemberController

Base URL: /api/members/actions

Endpoints

  • Assign Member to a Task: POST /{taskId}/assign/{teamMemberId}

    • Response Body:
    {
    "isAssignedId": 1,
    "taskId": 4,
    "teamMemberId": 2,
    "teamId": 3
}
    • Description: Assigns a member (admin or team member) to a task.

  • Mass Assign Members to a Task: POST /{taskId}/mass-assign

    • Request Body:
        [1, 2, 3, 4]
    • Response Body:
    [
    {
        "isAssignedId": 1,
        "taskId": 5,
        "teamMemberId": 7,
        "teamId": 2
    },
    {
        "isAssignedId": 2,
        "taskId": 5,
        "teamMemberId": 8,
        "teamId": 2
    },
    {
        "isAssignedId": 3,
        "taskId": 5,
        "teamMemberId": 9,
        "teamId": 2
    }
]
    • Description: Assigns multiple members (admins and/or team members) to a task. If a member is already assigned to the task they will be skipped, but the others will still be assigned.

  • Change Password: POST /{teamMemberId}/change-password

    • Request Body:
    {
    "oldPassword": "oldPass123",
    "newPassword": "newPass456"
}
    • Description: Updates the password field for a team member.

  • Get All Teams for a Team Member: GET /{teamMemberId}/teams

    • Response Body:
    [
    {
    "teamId": 1,
    "teamName": "Development Team"
    },
    {
    "teamId": 2,
    "teamName": "Marketing Team"
    }
]
    • Description: Returns a list of all the teams a team member is a part of.

  • Get Assigned Tasks For a Team Member: GET /{teamMemberId}/tasks

    • Response Body:
    [
    {
        "taskId": 101,
        "title": "Implement Login API",
        "description": "Develop the login functionality for the app",
        "isLocked": false,
        "status": "In Progress",
        "dateCreated": "2024-03-04",
        "dueDate": "2024-04-01",
        "teamId": 1,
        "assignedMembers": 
        [
            {
                "taskId": 101,
                "title": "Implement Login API",
                "description": "Develop the login functionality for the app",
                "isLocked": false,
                "status": "In Progress",
                "dateCreated": "2024-03-04",
                "dueDate": "2024-04-01",
                "teamId": 1,
                "priority": "HIGH",
                "assignedMembers": 
                [
                    {
                        "accountId": 1,
                        "userName": "Name",
                        "userEmail": "email@ex.com"
                    },
                    {
                        "accountId": 2,
                        "userName": "Name2",
                        "userEmail": "email_2@ex.com"
                    }
                ]
            },
            {
                "taskId": 102,
                "title": "Design Homepage",
                "description": "Create a wireframe for the homepage",
                "isLocked": true,
                "status": "Pending",
                "dueDate": null,
                "teamId": 2,
                "priority": "MEDIUM",
                "assignedMembers": []
            }
        ]
    },
    {
        "taskId": 102,
        "title": "Design Homepage",
        "description": "Create a wireframe for the homepage",
        "isLocked": true,
        "status": "Pending",
        "dueDate": null,
        "teamId": 2,
        "assignedMembers": []
    }
]
    • Description: Returns a list of every task a team member is assigned to.

NotificationController

Base URL: /api/notifications

Endpoints

  • Get Read Notifications: GET /{teamMemberId}/read

    • Response Body:
    {
    [
        {
            "notificationId": 1,
            "message": "Task Updated",
            "type": "TASK_EDITED",
            "isRead": true,
            "createdAt": "2024-03-15T10:30:00",
            "teamMemberId": 101,
            "taskId": 5
        },
        {
            "notificationId": 4,
            "message": "Project Deadline Extended",
            "type": "TASK_DUE_DATE_EDITED",
            "isRead": true,
            "createdAt": "2024-03-16T14:45:00",
            "teamMemberId": 101,
            "taskId": 8
        }
    ]
}
    • Description: Returns a list of all read notifications for a specific team member.

  • Get Unread Notifications: GET /{teamMemberId}/unread

    • Response Body:
    {
    [
        {
            "notificationId": 1,
            "message": "Task Updated",
            "type": "TASK_EDITED",
            "isRead": true,
            "createdAt": "2024-03-15T10:30:00",
            "teamMemberId": 101,
            "taskId": 5
        },
        {
            "notificationId": 4,
            "message": "Project Deadline Extended",
            "type": "TASK_DUE_DATE_EDITED",
            "isRead": true,
            "createdAt": "2024-03-16T14:45:00",
            "teamMemberId": 101,
            "taskId": 8
        }
    ]
}
    • Description: Returns a list of all unread notifications for a specific team member.

  • Mark Notification as Read: GET /{notificationId}/mark-as-read

    • Response Body:
    {
    "message": "Notification marked as read."
}
    • Description: Marks a notification as read.

  • Mark Notification as Unread: GET /{notificationId}/mark-as-unread

    • Response Body:
    {
    "message": "Notification marked as unread."
}
    • Description: Marks a notification as unread.

  • Delete Notification: DELETE /{notificationId}

    • Response Status:
        HTTP/1.1 204 No Content
    • Description: Deletes a notification from the database.

Path Variables

  • AdminController
    • {adminId} (integer, required): The ID of the admin
    • {teamMemberId} (integer, required): The ID of the team member
    • {teamId} (integer, required): The ID of the team
    • {taskId} (integer, required): The ID of the task
  • IsAssigned Controller
    • {teamMemberId} (integer, required): The ID of the team member
    • {taskId} (integer, required): The ID of the task
  • IsMemberOfController
    • {teamMemberId} (integer, required): The ID of the team member
    • {teamId} (integer, required): The ID of the team
  • TaskController
    • {taskId} (integer, required): The ID of the task
  • TeamController
    • {teamId} (integer, required): The ID of the team
  • TeamMemberController
    • {taskId} (integer, required): The ID of the task
    • {teamMemberId} (integer, required): The ID of the team member

DTO References

  • TaskDTO
    • title (string, required): The title of the task.
    • description (string, optional): A description of the task.
    • isLocked (boolean, optional): Whether the task is locked. Defaults to null if not provided.
    • status (string, optional): The task status (e.g., "To-Do", "In Progress", "Done"). Defaults to null if not provided.
    • dueDate (string, optional): The due date of the task in YYYY-MM-DD format.
    • priority (string, required): The priority of tha task. Must be one of LOW, MEDIUM, or HIGH.

Request and Response Examples

Below are some examples of API requests and responses.

CreateAdmin

POST /api/admin?name=John Doe&email=john.doe@example.com

  • Request Parameters

    • name (string, required): The name of the new admin.
    • email (string, required): The email of the new admin.

  • Request Response

    {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
}

ModifyAdminName

PUT /api/admin/1/update-name?newName=Jane Doe

  • Request Parameters

    • adminId (integer, required): The ID of the admin changing the members name.
    • newName (string, required): The new name of the member.

  • Response Body

    {
    "id": 1,
    "name": "Jane Doe",
    "email": "john.doe@example.com"
}

DeleteAdmin

DELETE /api/admin/1
  • Notes:
    • No request body required.
    • No response body returned.

CreateTask

POST /api/tasks?title=The Task Title&description=This is the description, it could get long.&isLocked=false&status=To-Do&teamId=3

  • Request Parameters

    • title (string, required): The title of the new task.
    • description (string, required): The description of the new task.
    • isLocked (boolean, required): A boolean of whether the new task is locked or not.
    • status (string, required): A string of the current status of the task.
    • teamId (integer, required): The ID of the team being assigned to the task.

  • Response Body

    {
    "taskId": 4,
    "title": "Design Database Schema",
    "description": "Create the database structure.",
    "isLocked": false,
    "status": "To-Do",
    "teamId": 3
}

Request and Response Testing Examples

Below are examples of some API requests and responses using Cypress.

  • AdminController

    • CreateAdmin
    cy.request({
    method: "POST",
    url: "http://localhost:8080/api/admin",
    qs: {
    name: "John Doe",
    email: "john@example.com",
    },
}).then((response) => {
    expect(response.status).to.eq(200);
    expect(response.body.name).to.eq("John Doe");
});
    • DeleteAdmin
    cy.request({
    method: "DELETE",
    url: "http://localhost:8080/api",
    qs: {
    adminId: 1,
    },
}).then((response) => {
    expect(response.status).to.eq(204);
});

    • TeamMemberController

    • Assign Member To Task

    const taskId = 5;
const teamMemberId = 7;

cy.request({
    method: "POST",
    url: "http://localhost:8080/api/tasks/${taskId}/assign/${teamMemberId}",
}).then((response) => {
    expect(response.status).to.eq(200);
    expect(response.body).to.have.property("taskId", taskId);
    expect(response.body).to.have.property("teamMemberId", teamMemberId);
});

Best Practices

Follow these practices to ensure efficiency and accuracy with all API requests.

Correct HTTP Methods

  • GET: Used to retrieve resources. Cannot modify data.
  • POST: Used to create resources.
  • PUT: Used to update existing resources.
  • DELETE: Used to delete resources.

Request Formatting

  • Ensure that required parameters are included in the request body or URL path.
  • Avoid sending unnecessary fields in API requests.

Error Codes

Code Description
200 OK - Request succeeded
201 Created - Resource successfully created
204 No Content - Resource deleted
400 Bad Request - Invalid input
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
500 Internal Server Error - Unexpected error

Example Error Response

```json
{
    "message": "Resource not found",
    "error": "NotFoundException",
    "statusCode": 404
}
```