Skip to content

Update API spec with latest CMS changes - #55

Open
rollki wants to merge 2 commits into
fivejars:4.xfrom
rollki:4.x
Open

Update API spec with latest CMS changes#55
rollki wants to merge 2 commits into
fivejars:4.xfrom
rollki:4.x

Conversation

@rollki

@rollki rollki commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Update API spec with latest CMS changes + resolve merge conflicts

What changed

The previous commit (611ca77) was a large AI-assisted rewrite of vc.adoc to modernise the AsciiDoc format:

  • Document header updated to proper AsciiDoc book format (:doctype: book, :toc: left, :toclevels: 3, :source-highlighter: highlight.js, :numbered:) — the TOC is now auto-generated, removing ~300 lines of manual link lists
  • All section anchors simplified (e.g. [[_bad_request_error]] → [[bad-request]])
  • Response tables reformatted from verbose 4-column to clean 3-column .Response Fields style
  • Code block source types normalised to [source,http] and [source,json] (was [source,highlightjs,highlight,nowrap])
  • Noise removed from HTTP examples (no more Content-Length, Content-Type headers in every block)
  • New sections added: Proxy API, Association Info, Combined API (frontpage + watch-screen), Instructor API, Worlds API, Widgets / App Settings, GroupXClass, Promo

This commit

The rewrite left two unresolved git merge conflict markers committed into the file. This PR resolves them:

  1. Conflict at the top — removed the stale 311-line manual TOC and the duplicate old-format "Method Not Allowed" section that was preserved from Updated upstream. The new format generates the TOC automatically, so this content was dead weight.
  2. Conflict at the bottom — added the Archived Videos section from Stashed changes, documenting two new endpoints that exist in the codebase but were missing from the spec:
  • GET /api/virtual-classes/v4.0/content-providers/{provider}/archived-videos — search, same parameters as Search Videos; returns items[].moderation_state: "archived"
  • GET /api/virtual-classes/v4.0/content-providers/{provider}/archived-videos/{videoId} — details, same shape as Fetch Video; returns videoBrief.moderation_state: "archived" and videoDetails.hashId

⚠️ Needs review

The bulk of this spec was regenerated by Claude from the CMS codebase. Deep analysis flagged several areas that should be verified by a developer familiar with the API before this is shared externally:

  • Response field names and nesting across all endpoints — particularly fields added recently (e.g. Worlds, Collections, Instructors)
  • Example JSON payloads — values are illustrative and may not reflect real API output exactly
  • Cross-references between sections (<>, <>) — anchor IDs were renamed and a wrong cross-reference would silently break the HTML render
  • The Archived Videos section is new and has not been validated against a live environment

@rollki
rollki requested a review from AndreyMaximov July 15, 2026 11:44
@rollki
rollki force-pushed the 4.x branch 2 times, most recently from 61e00f1 to 77fafd3 Compare July 17, 2026 08:35
thensalo added 2 commits July 17, 2026 15:04
Converts the entire document from legacy Asciidoctor snippet style to a
proper AsciiDoc book. No API content changes.

- Replace manual 300-line TOC with auto-generated :toc: left
- Add :doctype: book header with :numbered: and :icons: font
- Strip link:#...[] wrappers from all section headings
- Remove [width="100%",cols="..."] table header options
- Normalise source block types to [source,json]
- Live stream brief/search: rename topLevelCategory -> topLevelCategoryId
- Live stream brief/search: add description and equipment fields
- Live stream details: add chatEnabled field
- Sources: fix type description ("currently always m3u8")
- Sources: add provider and vimeoEventId fields with Vimeo proxy note
- Live stream: add Vimeo-hosted live stream response example
- Add Vimeo Playback Proxy endpoint documentation
- Combined API: correct URLs from /settings/v4.0/ to /api/virtual-classes/v4.0/
- Association info: fix billboards field url (was: link) + add centerFocusImage and premium
- Video details: remove videoFiles[].codec (not in implementation)
- Video brief: fix expirationDate description (field omitted when absent)
- Widgets API: annotate as not yet implemented in CMS
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants