Tea journaling on ATProto (alpha) forked from arabica.social/arabica
oolong docs api entities.md
11 kB · 287 lines
Markdown
at main

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.

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.