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:
{"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 #
{
"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 #
{
"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:
{"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 #
{
"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.