Capability: API (OpenAPI-backed)

Purpose

Describe the core HTTP API behavior and constraints. The OpenAPI 3.1 contract lives in spec/openapi.yaml.

Requirements

Requirement: Health check

The system SHALL expose a health endpoint for availability checks.

Scenario: Health endpoint returns OK

WHEN a client calls GET /health
THEN the server returns 200

Requirement: Authentication

The system SHALL support email+password registration and login.

WHEN a user registers with a valid email and password
THEN the server returns a JWT token
WHEN the user logs in with the same credentials
THEN the server returns a JWT token

Requirement: Public bookmarks visibility

The system SHALL allow anonymous users to view public bookmarks.

Scenario: List public bookmarks without auth

WHEN a client calls GET /bookmarks/public without a token
THEN the server returns 200 and a list of bookmarks

Requirement: Private bookmarks visibility

The system SHALL restrict private bookmark data to authenticated users.

Scenario: List my bookmarks requires auth

WHEN a client calls GET /bookmarks without a token
THEN the server returns an auth error
WHEN a client calls GET /bookmarks with a valid token
THEN the server returns 200 and the user's bookmarks

Requirement: Sync (LWW)

The system SHALL support last-write-wins (LWW) synchronization for folders and bookmarks.

Scenario: Push local changes then pull

WHEN an authenticated client calls POST /sync/push with folders/bookmarks
THEN the server stores the items using LWW semantics
WHEN the client calls GET /sync/pull
THEN the server returns folders/bookmarks and serverTime

Requirement: Admin user management (email-based)

The system SHALL treat exactly one configured email as an administrator and allow that user to manage/view users.

Scenario: Non-admin cannot access admin APIs

GIVEN an authenticated user whose email is not equal to ADMIN_EMAIL
WHEN the user calls GET /admin/users
THEN the server returns a 403 error

Scenario: Admin can list users

GIVEN an authenticated user whose email equals ADMIN_EMAIL
WHEN the user calls GET /admin/users
THEN the server returns 200 and a list of users

Scenario: Admin can view a user's bookmarks

GIVEN an authenticated admin user
WHEN the admin calls GET /admin/users/{id}/bookmarks
THEN the server returns 200 and that user's bookmarks

2.6 KiB Raw Blame History