Migration: Text Details with commentaries and version API

[tenzinsamten]

OpenPecha API

Step 1 — Get root expression

GET /v2/texts/{text_id}

Param	Type	In	Required	Description
text_id	string	path	Yes	OP expression ID

Response (200) — text_id=OQLxJCPiXhRTJK9yiTviM:

{
  "id": "OQLxJCPiXhRTJK9yiTviM",
  "title": { "bo": "འཕགས་པ་ཤེས་རབ་ཀྱི་ཕ་རོལ་ཏུ་ཕྱིན་པ་རྡོ་རྗེ་གཅོད་པ་ཞེས་བྱ་བ་ཐེག་པ་ཆེན་པོའི་མདོ།" },
  "language": "bo",
  "category_id": "rw8oWUd1WtwqeD2x0ZMSm",
  "license": "public",
  "date": "2025-11-24",
  "bdrc": "WA0RK0016",
  "contributions": [],
  "commentaries": ["pR5GpBvpuXeqFKMA7oy7", "dnfy5DBj19D0gE1Wh1IR7", "eMkglFLT1xz6O0gpsY1h7"],
  "translations": ["i5gV2cTZzE5NEI4DObMKu", "CudRcM2Y8ZUlGY55GP0cg"],
  "editions": ["NsJNvUuZZzobMp0kFCHkd"],
  "commentary_of": null,
  "translation_of": null,
  "alt_titles": null,
  "wiki": null
}

Code	Description
200	Text retrieved successfully
404	Resource not found
500	Internal server error

Step 2 — Get details per commentary/translation ID

Same endpoint GET /v2/texts/{text_id}, called once per ID from commentaries[] or translations[].

Commentary response (200) — text_id=pR5GpBvpuXeqFKMA7oy7:

{
  "id": "pR5GpBvpuXeqFKMA7oy7",
  "title": { "bo": "འཕགས་པ་ཤེས་རབ་ཀྱི་ཕ་རོལ་ཏུ་ཕྱིན་པ་རྡོ་རྗེ་གཅོད་པ...འགྲེལ་པ་ (Commentary)" },
  "language": "bo",
  "category_id": "rw8oWUd1WtwqeD2x0ZMSm",
  "license": "unknown",
  "date": null,
  "bdrc": null,
  "contributions": [],
  "commentaries": [],
  "translations": [],
  "editions": ["apyDqAuLlbJsHvrg4JfHB"],
  "commentary_of": "OQLxJCPiXhRTJK9yiTviM",
  "translation_of": null,
  "alt_titles": null,
  "wiki": null
}

Translation response (200) — text_id=i5gV2cTZzE5NEI4DObMKu:

{
  "id": "i5gV2cTZzE5NEI4DObMKu",
  "title": { "lzh": "金剛般若波羅密多經" },
  "language": "lzh",
  "category_id": "rw8oWUd1WtwqeD2x0ZMSm",
  "license": "unknown",
  "date": null,
  "bdrc": null,
  "contributions": [],
  "commentaries": [],
  "translations": ["gmqBB9aIgbuZhaFDK8s9m"],
  "editions": ["oTC8UvkeqazlX1aN3QHqo"],
  "commentary_of": null,
  "translation_of": "OQLxJCPiXhRTJK9yiTviM",
  "alt_titles": null,
  "wiki": null
}

Flow: 1 call for root expression + N calls per commentary/translation ID = N+1 total calls.

---

Replaces WeBuddhist API:

Versions

GET /api/v1/texts/{text_id}/versions?language=bo&skip=0&limit=10

Param	Type	In	Required	Description
text_id	string	path	Yes	WeBuddhist internal ID
language	string	query	No	Language code (e.g. bo, en)
skip	int	query	No	Records to skip
limit	int	query	No	Records to return

Response (200) — text_id=e159959d-2c0c-4f48-b02c-fbdc8c4a98e3:

{
  "text": {
    "id": "e159959d-2c0c-4f48-b02c-fbdc8c4a98e3",
    "pecha_text_id": "XVqq55pnANEKri9536Wa4",
    "title": "The Way of the Bodhisattva",
    "language": "en",
    "group_id": "76060053-0121-40d0-ba34-9c55ea7df2f3",
    "type": "version",
    "summary": "",
    "is_published": false,
    "created_date": "2025-11-27 16:22:29",
    "updated_date": "2025-11-27 16:22:29",
    "published_date": "2025-11-27 16:22:29",
    "published_by": "",
    "categories": ["76060053-0121-40d0-ba34-9c55ea7df2f3"],
    "views": 0,
    "likes": [],
    "source_link": "openpecha.org",
    "ranking": null,
    "license": "unknown"
  },
  "versions": [
    {
      "id": "ce0a5191-ea72-4e94-a270-1923d07e4d8e",
      "title": "བྱང་ཆུབ་སེམས་དཔའི་སྤྱོད་པ་ལ་འཇུག་པ།",
      "parent_id": null,
      "priority": null,
      "language": "bo",
      "type": "version",
      "group_id": "76060053-0121-40d0-ba34-9c55ea7df2f3",
      "table_of_contents": ["40dd0f80-8453-4a1c-b896-fba23ad598da"],
      "is_published": false,
      "created_date": "2025-11-27 16:22:22",
      "updated_date": "2025-11-27 16:22:22",
      "published_date": "2025-11-27 16:22:22",
      "published_by": "",
      "source_link": "bdrc.io",
      "ranking": null,
      "license": "Public Domain Mark"
    },
    {
      "id": "978c2d7a-dcbe-4afe-a109-5a62eb8624f1",
      "title": "菩薩行论",
      "parent_id": null,
      "priority": null,
      "language": "zh",
      "type": "version",
      "group_id": "76060053-0121-40d0-ba34-9c55ea7df2f3",
      "table_of_contents": ["9e452578-999a-4fc3-b575-a6d13e05a2e2"],
      "is_published": false,
      "created_date": "2025-11-27 16:22:35",
      "updated_date": "2025-11-27 16:22:35",
      "published_date": "2025-11-27 16:22:35",
      "published_by": "",
      "source_link": "openpecha.org",
      "ranking": null,
      "license": "unknown"
    }
  ]
}

Code	Description
200	Successful Response
422	Validation Error

Commentaries

GET /api/v1/texts/{text_id}/commentaries?skip=0&limit=10

Param	Type	In	Required	Description
text_id	string	path	Yes	WeBuddhist internal ID
skip	int	query	No	Records to skip (min: 0)
limit	int	query	No	Records to return (max: 100)

Response (200) — text_id=e159959d-2c0c-4f48-b02c-fbdc8c4a98e3:

[
  {
    "id": "f6ed393d-af2f-4a91-8ca5-9c7d6825c524",
    "pecha_text_id": "lZaPglaQxl922bjgGZWX7",
    "title": "བྱང་ཆུབ་སེམས་དཔའི་སྤྱོད་པ་ལ་འཇུག་པའི་འགྲེལ་པ་...",
    "language": "bo",
    "group_id": "1e767642-ebff-4f04-9404-790c5c565f69",
    "type": "commentary",
    "summary": "",
    "is_published": false,
    "created_date": "2025-11-27 16:22:42",
    "updated_date": "2025-11-27 16:22:42",
    "published_date": "2025-11-27 16:22:42",
    "published_by": "",
    "categories": ["76060053-0121-40d0-ba34-9c55ea7df2f3"],
    "views": 0,
    "likes": [],
    "source_link": "bdrc.io",
    "ranking": null,
    "license": "Public Domain Mark"
  },
  {
    "id": "ea68da11-5282-4573-aaed-39953c81ca66",
    "pecha_text_id": "lJkvG5ftzYgICpmIDGEGD",
    "title": "...",
    "language": "bo",
    "group_id": "18ce64fe-6a54-4238-8053-af41c3d7b98d",
    "type": "commentary",
    "summary": "",
    "is_published": false,
    "created_date": "2025-11-27 16:22:48",
    "updated_date": "2025-11-27 16:22:48",
    "published_date": "2025-11-27 16:22:48",
    "published_by": "",
    "categories": ["76060053-0121-40d0-ba34-9c55ea7df2f3"],
    "views": 0,
    "likes": [],
    "source_link": "bdrc.io",
    "ranking": null,
    "license": "Public Domain Mark"
  }
]

Code	Description
200	Successful Response
422	Validation Error

---

Response Mapping — Versions

OP flow: GET /v2/texts/{id} → extract translations[] → GET /v2/texts/{each_id}
Replaces: GET /api/v1/texts/{id}/versions

WeBuddhist	OpenPecha	Notes
text.id	—	WeBuddhist-only, no OP equivalent
text.pecha_text_id	editions[0]	WeBuddhist stored edition (manifestation) ID, not expression ID
text.title	title (1st call)	WeBuddhist: single string. OP: multilingual object { "bo": "..." }
text.language	language (1st call)	Direct mapping
text.group_id	—	WeBuddhist-only
text.type	—	Always "version" in WeBuddhist. OP uses translation_of field instead
text.summary	—	Deprecated
text.is_published	—	To be removed
text.created_date	—	To be removed
text.updated_date	—	To be removed
text.published_date	date (1st call)	Direct mapping
text.published_by	contributions[] (1st call)	OP: array of { person_id, role }. WeBuddhist: string
text.categories	category_id (1st call)	WeBuddhist: array. OP: single string
text.views	—	WeBuddhist-only
text.likes	—	WeBuddhist-only
text.source_link	—	Not in expression. Available per edition via GET /v2/texts/{id}/editions
text.ranking	—	To be removed
text.license	license (1st call)	WeBuddhist: free-form string. OP: strict enum (public, unknown, cc-by, etc.)
versions[].id	—	WeBuddhist-only
versions[].title	title (2nd call)	WeBuddhist: single string. OP: multilingual object
versions[].language	language (2nd call)	Direct mapping
versions[].type	—	Always "version". OP uses translation_of field instead
versions[].group_id	—	WeBuddhist-only
versions[].parent_id	—	WeBuddhist-only
versions[].priority	—	WeBuddhist-only
versions[].table_of_contents	—	Not in OP expression. Available at edition level
versions[].is_published	—	To be removed
versions[].created_date	—	To be removed
versions[].updated_date	—	To be removed
versions[].published_date	date (2nd call)	Direct mapping
versions[].published_by	contributions[] (2nd call)	OP: array of { person_id, role }. WeBuddhist: string
versions[].source_link	—	Not in expression. Available per edition via GET /v2/texts/{id}/editions
versions[].ranking	—	To be removed
versions[].license	license (2nd call)	WeBuddhist: free-form string. OP: strict enum
—	translation_of	New. Points back to parent expression ID
—	editions[]	New. Edition/manifestation IDs
—	commentaries[]	New. Commentary IDs for this translation
—	translations[]	New. Further translation IDs
—	bdrc	New. BDRC work ID
—	wiki	New
—	alt_titles	New
—	category_id	New. Single string (not array)

---

Response Mapping — Commentaries

OP flow: GET /v2/texts/{id} → extract commentaries[] → GET /v2/texts/{each_id}
Replaces: GET /api/v1/texts/{id}/commentaries

WeBuddhist	OpenPecha	Notes
[].id	—	WeBuddhist-only
[].pecha_text_id	editions[0]	WeBuddhist stored edition ID, not expression ID
[].title	title	WeBuddhist: single string. OP: multilingual object { "bo": "..." }
[].language	language	Direct mapping
[].group_id	—	WeBuddhist-only
[].type	—	Always "commentary". OP uses commentary_of field instead
[].summary	—	Deprecated
[].is_published	—	To be removed
[].created_date	—	To be removed
[].updated_date	—	To be removed
[].published_date	date	Direct mapping
[].published_by	contributions[]	OP: array of { person_id, role }. WeBuddhist: string
[].categories	category_id	WeBuddhist: array. OP: single string
[].views	—	WeBuddhist-only
[].likes	—	WeBuddhist-only
[].source_link	—	Not in expression. Available per edition via GET /v2/texts/{id}/editions
[].ranking	—	To be removed
[].license	license	WeBuddhist: free-form string. OP: strict enum
—	commentary_of	New. Points back to parent expression ID
—	editions[]	New. Edition/manifestation IDs
—	commentaries[]	New. Sub-commentary IDs
—	translations[]	New. Translation IDs for this commentary
—	bdrc	New. BDRC work ID
—	wiki	New
—	alt_titles	New