# Entity API JSON surface for the five active oolong entities. The `/api/*` handlers and the page-route JSON views call the same loader (`EntityViewLoader`, `RecordCRUDWrite`), so permissions, reference joining, social state, moderation filtering, and CIDs are identical whichever route a client uses. | Collection path | NSID | Record | |-----------------|------|--------| | `teas` | `social.oolong.alpha.tea` | `Tea` | | `brews` | `social.oolong.alpha.brew` | `Brew` | | `vendors` | `social.oolong.alpha.vendor` | `Vendor` | | `vessels` | `social.oolong.alpha.vessel` | `Vessel` | | `infusers` | `social.oolong.alpha.infuser` | `Infuser` | `cafe` and `drink` are unsupported: no route serves them. ## Errors Every error body has the same shape: ```json {"error": "human readable message", "code": "invalid_request"} ``` | Code | Status | Meaning | |------|--------|---------| | `invalid_request` | 400 | Malformed path parameter, query, or request body. | | `authentication_required` | 401 | No session, or the session expired. | | `permission_denied` | 403 | Session lacks the permission for this operation, or a cross-site write was rejected. | | `not_found` | 404 | Record or actor not found. | | `method_not_allowed` | 405 | Wrong HTTP method. | | `service_unavailable` | 502 | The viewer's own repository could not be read (PDS unreachable). Distinguishes an outage from a missing record. | | `internal_error` | 500 | Unexpected server failure. | ## `GET /api/{collection}/{actor}/{id}` Rich public entity detail: the decoded record, its AT-URI and CID, author identity, social state (likes, comments, moderation flags), and backlinks. `{actor}` is the record owner's handle or DID; it is passed through as `?owner=` internally, which is what the loader keys off. ### Response ```json { "record": {"rkey": "3kabc", "name": "Sencha", "...": "..."}, "subject_uri": "at://did:plc:abc123/social.oolong.alpha.tea/3kabc", "subject_cid": "bafy...", "author": {"did": "did:plc:abc123", "handle": "alice.test", "display_name": "Alice", "avatar": "https://..."}, "social": { "is_liked": false, "like_count": 3, "comment_count": 1, "comments": [], "is_moderator": false, "can_hide_record": false, "can_block_user": false, "is_record_hidden": false }, "backlinks": { "library_entries": [], "library_count": 0, "usage": [], "usage_count": 0, "rating_average": 0, "rating_count": 0 }, "backlinks_detail_url": "/teas/alice.test/3kabc/backlinks", "is_own_profile": false, "is_authenticated": true, "share_url": "/teas/alice.test/3kabc", "entity_type": "tea", "entity_count": 0 } ``` | Field | Type | Description | |-------|------|-------------| | `record` | `Tea \| Brew \| Vendor \| Vessel \| Infuser` | Decoded record with reference joins (`vendor`, `tea`, `vessel_obj`, `infuser_obj`). | | `subject_uri` | `string` | AT-URI of the record. | | `subject_cid` | `string` | CID of the record (for like/comment forms). | | `author` | `object` | `did`, `handle`, `display_name`, `avatar`. | | `social` | `object` | Viewer-relative social and moderation state. | | `social.comments` | `array` | Threaded comments (empty when none). | | `backlinks` | `object` | Records referencing this one (`library_entries`) plus usage groups; empty arrays when none. | | `backlinks_detail_url` | `string` | Backlinks page path. | | `is_own_profile` | `bool` | Whether the viewer owns the record. | | `is_authenticated` | `bool` | Whether the request carried a session. | | `share_url` | `string` | Canonical page path for the record. | | `entity_type` | `string` | Lowercase entity noun. | | `entity_count` | `int` | Entity-specific count (0 for oolong entities today). | `GET /{collection}/{actor}/{id}` serves this same body to a request that sends `Accept: application/json` (`routing.SPAOrJSON`). A browser navigation gets the Solid shell, which fetches this endpoint itself. ## `GET /api/{collection}/{actor}/{id}/backlinks` Backlinks page data as JSON. ### Query parameters | Param | Type | Default | Description | |-------|------|---------|-------------| | `usage` | `string` | — | Usage group key to page. | | `page` | `int` | 1 | Usage page (1–10000). Invalid values are rejected. | ### Response ```json { "entity_name": "Sencha", "entity_type": "tea", "back_url": "/teas/alice.test/3kabc", "detail_url": "/teas/alice.test/3kabc/backlinks", "result": {"library_entries": [], "library_count": 0, "usage": [], "usage_count": 0, "rating_average": 0, "rating_count": 0} } ``` `Backlinks.Result`: | Field | Type | Description | |-------|------|-------------| | `library_entries` | `Entry[]` | Records whose `sourceRef` chain leads to this one. | | `library_count` | `int` | Total library entries. | | `usage` | `UsageGroup[]` | Records referencing this one, grouped by field. | | `usage_count` | `int` | Total usage records. | | `rating_average` | `number` | Average rating across usage records. | | `rating_count` | `int` | Number of rated usage records. | `Entry`: `did`, `handle`, `display_name`, `avatar_url`, `record_uri`, `collection`, `rkey`, `created_at`, `title`, `rating`, `has_rating`, `chain_depth`. `UsageGroup`: `key`, `label`, `entries` (`Entry[]`), `count`, `rating_average`, `rating_count`, `page`, `per_page`, `has_prev`, `has_next`. ### Rating visibility Tea and vendor records follow their owner's `profile_stats_visibility` setting (see `docs/api/settings.md`). When the owner set the matching aggregate to `private`, every viewer except the owner receives `rating_average: 0`, `rating_count: 0`, `library_entries[].rating: 0`, `library_entries[].has_rating: false`, zeroed `usage[].rating_average`/`usage[].rating_count`, and zeroed `usage[].entries[].rating`/`has_rating` from both this endpoint's `backlinks` object and `GET /api/{collection}/{actor}/{id}/backlinks`. The same gate covers both JSON reads; the Solid record and backlinks pages only ever show what they return. Counts, names, links, and the record's own `rating` field are unaffected; other entity types have no aggregate rating to hide. Enforcement: `backlinksForViewer` → `hideBacklinkRatings` in `internal/handlers/entity_json.go`. ### Failure behaviour A missing public record (`400`/`404` from the PDS) returns `404 not_found`. Other upstream failures return `502 service_unavailable` and do not expose internal details (`EntityViewLoader.loadFromPDS` in `internal/handlers/entity_view_loader.go`). The viewer's own-record read (`GET /api/{collection}/{id}`) uses the same distinction. A moderation-hidden entity is `404 not_found` for every viewer except its owner and moderators, who still get the record with `social.is_record_hidden: true` (`canReadEntityJSON`). The page-route metadata applies the same gate, so a hidden record reads as missing rather than leaking its name. ## `GET /brews/new` and `GET /brews/{id}/edit` (JSON negotiation) With `Accept: application/json`, these page routes return the steep-form bundle: ```json {"brew": null, "teas": [], "vessels": [], "infusers": []} ``` `brew` is the saved record on the edit route. Reads use the same strict error mapping as `/api/manage`; a missing edit record is `404 not_found`. ## `GET /api/{collection}/{id}` The viewer's own record, shaped to seed an edit form. Authentication is required and only the viewer's own repository is read. ### Response ```json { "rkey": "3kabc", "uri": "at://did:plc:abc123/social.oolong.alpha.brew/3kabc", "cid": "bafy...", "record": {"rkey": "3kabc", "tea_rkey": "3ktea", "style": "longSteep", "...": "..."} } ``` | Field | Type | Description | |-------|------|-------------| | `rkey` | `string` | Record key. | | `uri` | `string` | AT-URI of the record. | | `cid` | `string` | CID of the record. | | `record` | `object` | Decoded record model (see below). | ### Errors | Status | Code | When | |--------|------|------| | 400 | `invalid_request` | Malformed record key. | | 401 | `authentication_required` | No session, or the session expired. | | 404 | `not_found` | The viewer's repository answered "record not found" (`oolongRecordJSON` in `internal/oolong/handlers/record_json.go`). | | 502 | `service_unavailable` | The record read failed upstream (PDS unreachable). Not reported as `404`. | ## Writes | Method | Path | Body | |--------|------|------| | `POST` | `/api/{collection}` | Create; returns the record model with `rkey` set. | | `PUT` | `/api/{collection}/{id}` | Replace; returns the record model with `rkey` set. | | `DELETE` | `/api/{collection}/{id}` | Delete; returns `204 No Content`. | Bodies may be `application/json` (snake_case keys matching the request model) or form-encoded (the same keys as form field names). Reference fields (`vendor_rkey`, `tea_rkey`, `vessel_rkey`, `infuser_rkey`) are rkeys of the viewer's own records. Validation and store failures answer `400 invalid_request` and `401 authentication_required` / `502 service_unavailable` in the error shape above; an expired session on the write path is `401 authentication_required`. A successful write answers JSON, with no HTML or redirect variant, so a client reads the model straight from the response. ## Record models Timestamps are RFC 3339 strings. Optional fields are omitted when empty. ### `Tea` | Field | Type | Notes | |-------|------|-------| | `rkey` | `string` | | | `name` | `string` | Required. | | `category` | `string` | `green`, `yellow`, `white`, `oolong`, `red`, `black`, `dark`, `herbal`, `rooibos`, `flavored`, `blend`, `other`. | | `origin` | `string` | | | `harvest_year` | `int` | | | `description` | `string` | | | `link` | `string` | | | `vendor_rkey` | `string` | Reference to a `Vendor`. | | `rating` | `int` | 1–10. | | `closed` | `bool` | | | `source_ref` | `string` | AT-URI this record was derived from. | | `created_at` | `string` | | | `vendor` | `Vendor` | Joined on reads. | ### `Brew` | Field | Type | Notes | |-------|------|-------| | `rkey` | `string` | | | `tea_rkey` | `string` | Required reference to a `Tea`. | | `style` | `string` | `longSteep`, `coldBrew`. | | `vessel_rkey` | `string` | Reference to a `Vessel`. | | `infusion_method` | `string` | `tea-bag`, `loose-leaf`, `infuser`. | | `infuser_rkey` | `string` | Reference to an `Infuser`. | | `temperature` | `number` | | | `leaf_grams` | `number` | | | `water_amount` | `int` | | | `time_seconds` | `int` | | | `tasting_notes` | `string` | | | `rating` | `int` | 1–10. | | `created_at` | `string` | | | `tea` | `Tea` | Joined on reads. | | `vessel_obj` | `Vessel` | Joined on reads. | | `infuser_obj` | `Infuser` | Joined on reads. | ### `Vendor` `rkey`, `name` (required), `location`, `website`, `description`, `source_ref`, `created_at`. ### `Vessel` `rkey`, `name` (required), `style` (`teapot`, `mug`, `jar`, `matcha-bowl`, `other`), `capacity_ml`, `material`, `description`, `link`, `source_ref`, `created_at`. ### `Infuser` `rkey`, `name` (required), `style` (`basket`, `ball`, `sock`, `other`), `material`, `description`, `link`, `source_ref`, `created_at`.