URL normalization
Keep the original URL, normalize conservatively, and make tracking-parameter removal transparent and configurable.
Bookmark API architecture
Model the life of a link before you multiply endpoints.
A dependable bookmark API needs stable identity, careful URL normalization, folders and tags, explicit permissions, change feeds, conflicts, bulk migration, and inspectable exports.
REST resourcesSync cursorsOptimistic concurrencyImport & export
Core resource
Separate stable identity from mutable URL metadata
Do not use the URL itself as the primary key. Redirects, edits, intentional duplicates, and shared context require a stable record ID.
| Field | Purpose | Design note |
|---|---|---|
id | Stable identity | Server-generated and unchanged across title or URL edits. |
url | Original destination | Preserve submitted value; store a separate normalized comparison value. |
title | User-facing retrieval | Editable; do not overwrite automatically after the user changes it. |
note | Reason and context | Treat as potentially sensitive and searchable within permission scope. |
folder_id | Primary location | Tree semantics differ from many-to-many tags. |
revision | Concurrency and sync | Use a server revision or entity tag to prevent silent overwrites. |
System behaviors
Design the difficult edges explicitly
The API becomes trustworthy when clients can predict what happens during duplicates, moves, deletes, offline edits, and partial imports.
Folders and tags
Model ordered folder trees separately from reusable many-to-many tag relationships.
Search
Document indexed fields, ranking, filters, permission boundaries, and whether page content is actually stored.
Sync
Use an opaque cursor or revision sequence, return tombstones, and define field-level conflict rules.
Bulk migration
Stage imports, report per-item warnings, accept idempotency keys, and provide complete structured exports.
Permissions
Use narrow scopes, workspace roles, revocation, and minimal webhook payloads for sensitive link data.
Small first version
Ship predictable semantics before advanced extraction.
A focused API can support create, retrieve, patch, archive, list and filter, folders, tags, a change cursor, import, and export. Add snapshots, full-text page indexing, semantic search, sharing, and webhooks after the core is reliable.
Acceptance scenarios
- Same URL with different notes
- Concurrent title and tag updates
- Folder move while offline
- Deleted parent folder
- Large import with partial failures
- Revoked workspace access
- Export and clean re-import