# 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.

#### Scenario: Register then 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