Xu_BrowserBookmark/openspec/specs/api/spec.md

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