calendar-plugin/requirements/api.md

API Requirements

Purpose

Define the non-CalDAV HTTP API contract for calendar, user-access workflow, and operational endpoints used by the plugin UI and tests.

Scope

This document covers:

• API base path and versioning
• Event CRUD endpoints
• CalDAV-user workflow endpoints
• Standard request/response and error contracts
• Authn/Authz expectations for API calls

Normative Boundaries

• API authentication and token/session behavior are defined in requirements/authentication.md.
• Authorization matrix and role constraints are defined in requirements/authorization.md.
• Error payload/status normalization is defined in requirements/error_model.md.
• Recurrence exception behavior is defined in requirements/recurrence_exceptions.md.
• Data persistence schema is defined in requirements/data_schema.md.

API Baseline

• Base path: /wp-json/calendar/v1
• If url_slug is configured in setup, canonical API paths are prefixed: /<url_slug>/wp-json/calendar/v1.
• Content type: application/json; charset=utf-8
• Time format: ISO 8601 with timezone offset
• All endpoints must be deterministic under Europe/London default timezone assumptions unless a timezone is explicitly supplied.

Versioning

• Breaking changes require a new version namespace (v2, etc.).
• Non-breaking additions are permitted in the current version.
• Deprecated fields/endpoints must remain for at least one release cycle with documentation notice.

Event Endpoints

Create Event

• POST /events
• Requires calendar write capability.
• Request body supports fields in requirements/editor.md.
• Response: 201 with created event payload and identifiers.

List Events

• GET /events
• Supports query params:
  • from (optional)
  • to (optional)
  • view (optional: list, day, week, month, year)
  • page and per_page (optional)
• Response: 200 with array plus pagination metadata if paged.

Get Event

• GET /events/{event_id}
• Response: 200 with event payload or 404.

Update Event

• PUT /events/{event_id} or PATCH /events/{event_id}
• Requires calendar write capability.
• Must enforce optimistic concurrency via version/etag precondition checks.
• Response: 200 with updated event payload.

Delete Event

• DELETE /events/{event_id}
• Requires calendar write capability.
• Response: 204 on success.

Delete Single Occurrence

• DELETE /events/{event_id}/occurrences/{occurrence_key}
• Requires calendar write capability.
• Deletes only one occurrence in a recurring series by creating an exception.
• Must not split the underlying recurring series.
• Response: 204 on success.

CalDAV User Workflow Endpoints

Register

• POST /users/register
• Public endpoint with abuse controls.
• Creates account in pending_approval.
• Registration is implicitly a write-access request; no separate request endpoint exists.

Verify Email

• POST /users/verify
• Consumes single-use verification token.
• Marks email as verified while account remains pending_approval until admin approval.

Forgot Password

• POST /users/forgot-password
• Issues password reset token by email.

Reset Password

• POST /users/reset-password
• Consumes single-use reset token.

Admin User List/Update/Delete

• GET /admin/users
• PATCH /admin/users/{user_id}
• DELETE /admin/users/{user_id}
• Admin-only endpoints for approval state transitions and user removal.

Admin Diagnostics

• GET /admin/diagnostics?limit=20
• Admin-only endpoint.
• Returns recent request/response trace entries for operational troubleshooting.
• Sensitive fields must remain redacted per requirements/observability.md.

Response Contract

Success responses should include:

• data: endpoint payload
• meta: optional metadata (pagination, timestamps, version)

Error responses should include:

• error.code (stable machine-readable code)
• error.message (human-readable summary)
• error.details (optional field-level/context details)

Validation and Error Statuses

• 400 malformed request
• 401 unauthenticated
• 403 unauthorized
• 404 not found
• 409 conflict (state transition conflict)
• 412 precondition failed (etag/version mismatch)
• 422 semantic validation failure
• 429 rate-limited
• 500 internal server error

Security Requirements

• HTTPS required for all authenticated API operations.
• CSRF/nonce protections for cookie-authenticated endpoints.
• Rate limiting for register/verify/reset/login-like flows.
• Error responses must avoid user enumeration leakage.

Verification Requirements

Acceptance should verify:

• Endpoint paths and methods behave as documented.
• Validation and error payloads are consistent.
• Single-occurrence delete creates recurrence exception rather than split series.
• Authz rules enforce role/access constraints.