Mahdaad Dev Handbook

Appearance

RESTful principles Resource: Tasks ​

  • GET /api/v1/tasks
    • Purpose: Retrieve a list of all tasks.
    • Standard Response: 200 OK
  • POST /api/v1/tasks
    • Purpose: Create a new task.
    • Standard Response: 201 Created
  • GET /api/v1/tasks/{taskId}
    • Purpose: Retrieve a single, specific task.
    • Standard Response: 200 OK
  • PUT /api/v1/tasks/{taskId}
    • Purpose: Fully update/replace an existing task.
    • Standard Response: 200 OK
  • PATCH /api/v1/tasks/{taskId}
    • Purpose: Partially update a task (e.g., just changing its status).
    • Standard Response: 200 OK
  • DELETE /api/v1/tasks/{taskId}
    • Purpose: Delete a task.
    • Standard Response: 204 No Content

Nested Resource: Comments on a Task ​

  • GET /api/v1/tasks/{taskId}/comments
    • Purpose: Retrieve all comments for a specific task.
    • Standard Response: 200 OK
  • POST /api/v1/tasks/{taskId}/comments
    • Purpose: Create a new comment on a specific task.
    • Standard Response: 201 Created
  • DELETE /api/v1/tasks/{taskId}/comments/{commentId}
    • Purpose: Delete a specific comment from a task.

Logical, clearly named, and nested URLs ​

1. Use Nouns, Not Verbs The URL should represent a "thing" (a noun), and the HTTP method (GET, POST, DELETE) should represent the action.

  • Good: GET /api/v1/tasks
  • Bad: GET /api/v1/getAllTasks

2. Logical Nesting for Relationships When a resource belongs to another, you show this relationship through nesting in the URL.

  • To get all tasks within a specific project (e.g., project ID proj_123), the endpoint is logical and nested: GET /api/v1/projects/proj_123/tasks
  • To get a specific comment (e.g., comment ID comment_456) on a specific task (task ID task_789): GET /api/v1/tasks/task_789/comments/comment_456

3. Clear and Consistent Naming Use plural nouns for collections and be consistent.

  • Good: Use /projects, /tasks, /users.
  • Bad: Mixing plurals and singulars like /project, /tasks, /userList.

401 Unauthorized ​

  • Purpose: Authenticate the user. The request lacks valid authentication credentials.
  • Scenario: A user attempts to get a list of tasks but has not provided a valid API token.
  • Request:
    GET /api/v1/tasks
  • Response Body:
  • JSON

{
"error": "Authentication failed",
"message": "A valid API token is required to access this resource."
}

  • Standard Response: 401 Unauthorized

403 Forbidden ​

  • Purpose: Authorize the user. The user is authenticated, but does not have the necessary permissions for the requested action.
  • Scenario: A user with read-only permissions tries to delete a task.
  • Request:
    DELETE /api/v1/tasks/
  • Response Body:
  • JSON

{
"error": "Forbidden",
"message": "You do not have the required permissions to delete this task."
}

  • Standard Response: 403 Forbidden

500 Internal Server Error ​

  • Purpose: Handle unexpected server-side errors.
  • Scenario: An unexpected issue occurs on the server (e.g., database connectivity issue) when a user tries to create a new task.
  • Request:
    POST /api/v1/tasks
  • Response Body:
  • JSON

{
"error": "Internal Server Error",
"message": "An unexpected error occurred. Please try again later or contact support."
}

  • Standard Response: 500 Internal Server Error