66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# 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
|