Skip to content

API.md

Latest commit

 

History

History
254 lines (219 loc) · 7.08 KB

API.md

File metadata and controls

254 lines (219 loc) · 7.08 KB

API Reference

Base URL defaults to http://localhost:8080/api in development and production (proxied through nginx). All authenticated requests rely on an HttpOnly session cookie containing a JWT signed with HS256.

Authentication

POST /auth/login

  • Role: Public
  • Body: 
    {
  "username": "string",
  "password": "string"
}
  • Responses:
    • 200 OK – sets session cookie and returns current user metadata. 
      {
  "id": "uuid",
  "username": "admin",
  "role": "ADMIN"
}
    • 401 Unauthorized – invalid credentials.
    • 429 Too Many Requests – login rate limiter triggered (5 attempts/minute per IP).

POST /auth/logout

  • Role: Authenticated (any role)
  • Effect: Clears session cookie.
  • Responses: 204 No Content.

GET /auth/me

  • Role: Authenticated (any role)
  • Responses:
    • 200 OK – returns the decoded JWT payload (id, username, role).
    • 401 Unauthorized – missing/invalid cookie.

Health

GET /health

  • Role: Public
  • Response: 
    {
  "status": "ok",
  "time": "2024-01-01T12:00:00.000Z"
}

Calendar items

All item endpoints require authentication. Non-admin users can read all items but may only mutate items where ownerId matches their user ID. Admins can manage every item and can set the owner_id explicitly when creating.

GET /items?month=YYYY-MM

  • Role: Authenticated
  • Response: Array of items within the requested month. 
    [
  {
    "id": "uuid",
    "date": "2024-10-07T00:00:00.000Z",
    "type": "EVENT",
    "title": "Soccer practice",
    "body": "Bring cleats",
    "ownerId": "uuid",
    "owner": { "id": "uuid", "username": "alex" },
    "createdAt": "2024-09-01T18:00:00.000Z",
    "updatedAt": "2024-09-01T18:00:00.000Z"
  }
]
  • Errors: 400 Bad Request if month is missing or malformed.

GET /items/day/:date

  • Role: Authenticated
  • Params: date in YYYY-MM-DD format.
  • Response: Array of items for the specific day.
  • Errors: 400 Bad Request (invalid date).

POST /items

  • Role: Authenticated
  • Body: 
    {
  "date": "2024-10-07",
  "type": "EVENT",
  "title": "Dentist",
  "body": "9am check-up",
  "owner_id": "uuid" // optional, admin only
}
  • Responses: 200 OK with created item JSON.

PUT /items/:id

  • Role: Item owner or admin
  • Body: any subset of { "title", "body", "type" }.
  • Responses:
    • 200 OK – updated item.
    • 404 Not Found – item does not exist.
    • 403 Forbidden – non-owner attempting to modify another user's item.

DELETE /items/:id

  • Role: Item owner or admin
  • Responses:
    • 204 No Content – successfully deleted.
    • 404 Not Found – missing item.
    • 403 Forbidden – non-owner delete attempt.

Schedule

GET /schedule?month=YYYY-MM

  • Role: Authenticated
  • Response: 
    {
  "days": {
    "2024-10-07": { "owner": "Parent A", "label": "Mom", "color": "indigo", "blockId": "uuid" }
  },
  "blocks": [
    {
      "id": "uuid",
      "startDate": "2024-10-07",
      "endDate": "2024-10-13",
      "owner": "Parent A",
      "label": "Mom",
      "color": "indigo",
      "createdAt": "2024-09-28T15:30:00.000Z",
      "updatedAt": "2024-09-28T15:30:00.000Z"
    }
  ]
}

Admin block management (/schedule/blocks)

  • Role: Admin only (role === "ADMIN").
  • Endpoints:
    • GET /schedule/blocks?start=YYYY-MM-DD&end=YYYY-MM-DD
      • Optional start/end filters (inclusive). Returns sorted blocks.
    • POST /schedule/blocks 
      {
  "startDate": "2024-10-07",
  "endDate": "2024-10-13",
  "owner": "Parent A",
  "label": "Mom",
  "color": "indigo"
}
    • PUT /schedule/blocks/:id – update subset of fields; label/color can be set to null to remove.
    • DELETE /schedule/blocks/:id
  • Errors: 400 Bad Request (invalid dates or empty payload), 403 Forbidden, 404 Not Found for missing block.

Cycle template management (/schedule/templates/cycle)

  • Role: Admin only
  • Endpoints:
    • GET /schedule/templates/cycle – returns the active template or null.
    • PUT /schedule/templates/cycle 
      {
  "name": "Default 2-2-5-5",
  "days": [
    { "dayIndex": 0, "owner": "Parent A", "label": "Mom", "color": "indigo" },
    { "dayIndex": 1, "owner": "Parent A" },
    { "dayIndex": 27, "owner": "Parent B", "label": "Dad" }
  ]
}
      • days must include between 1 and 42 entries covering contiguous indices starting at 0 (e.g., 0-41 for a six-week cycle).
    • POST /schedule/templates/cycle/apply 
      {
  "anchorDate": "2024-10-07",
  "cycles": 6,
  "replaceExisting": true
}
      • Generates schedule blocks starting at anchorDate for cycles * template_length days (default 6 cycles) and optionally deletes overlapping future blocks.
  • Responses: Summary payload including number of blocks created and range applied.

User management (admin)

All routes below are prefixed with /admin because of router registration (/api/admin/...). Only admins may access these endpoints.

GET /admin/users

  • Returns list of users with id, username, role, createdAt.

POST /admin/users

  • Body: 
    {
  "username": "casey",
  "password": "changeme",
  "role": "USER"
}
  • Response: 200 OK with newly created user metadata.

PUT /admin/users/:id

  • Body: 
    {
  "password": "newpass", // optional
  "role": "ADMIN"         // optional
}
  • At least one field is required; returns updated user.

DELETE /admin/users/:id

  • Response: 204 No Content.

Error model

Errors are returned as JSON objects of the form:

{ "error": "description" }

Common status codes:

Status Meaning
400 Validation error (missing parameters, bad dates).
401 Missing or invalid authentication cookie.
403 Authenticated but lacks required admin role.
404 Entity not found.
409 Reserved for conflict scenarios (not currently used).
429 Rate limited (/auth/login).
500 Unexpected server error.

RBAC summary

Role Permissions
USER Read/write own items, read shared schedule, read list of items.
ADMIN Full access: manage users, manage schedule blocks/templates, create items on behalf of others, view everything.

Curl quickstart

# Login as admin and store cookie
curl -c cookies.txt -H 'Content-Type: application/json' \
  -X POST http://localhost/api/auth/login \
  -d '{"username":"admin","password":"changeme"}'

# Create a schedule block (admin only)
curl -b cookies.txt -H 'Content-Type: application/json' \
  -X POST http://localhost/api/schedule/blocks \
  -d '{"startDate":"2024-10-07","endDate":"2024-10-13","owner":"Parent A","label":"Mom","color":"indigo"}'

# List users (admin only)
curl -b cookies.txt http://localhost/api/admin/users