Conversation
Sync the API spec with the Tutorial v2 backend changes (goplus/builder-backend#350/goplus#353/goplus#354), documenting the transitional expand-release shape: - Course gains kind (immutable, guided | playground) and kind-specific opaque content; the top-level entrypoint/prompt copies are marked deprecated and noted for removal by the API contract release. - Course create/update accept both the kind+content shape and the transitional legacy flat payload; update documents kind immutability. - CourseSeries gains kind; series lists gain a kind filter; series create/update document the kind semantics. - New POST /user/courses/playground/copilot-context endpoint. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Aligns with GeneratePlaygroundCourseCopilotContextInput in module_CourseApis.ts and the backend validation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The endpoint draws from the copilotMessage quota, so its 403/429 responses follow the same contracts as the other quota-backed endpoints (40301/42901 with Retry-After). Also state the refund policy precisely: server-side failures refund, client cancellation does not. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Course.content now shows both kind-specific shapes, and every mention of the transitional shape's removal points at the concrete contract PR (goplus/builder-backend#352) instead of an unnamed future release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…guided too Matches goplus/builder-backend#353: the flat entrypoint/prompt shape applies to guided creates whether kind is omitted or given, and content wins when both are present.
Pairs with goplus/builder-backend#352 (migration 018 plus its application change): the transitional shapes introduced for the expand phase are gone. - `Course` drops the deprecated top-level `entrypoint` / `prompt`; `content` becomes a `oneOf` of the new `GuidedCourseContent` and `PlaygroundCourseContent` schemas, selected by `kind`. - `POST /user/courses` requires `kind` and `content`; the legacy flat payload is no longer documented. `PATCH /courses/{id}` no longer accepts the flat fields and states that `content` is replaced as a whole. - `POST /user/course-series` requires `kind`. BREAKING CHANGE: clients must send `kind` + `content` (and `kind` on course series) and must read guided course data from `content`.
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #3403 / #3422. Documents the API contract release for course kinds: the second half of the expand-contract pair whose first half is #3471.
Important
Stacked on #3471: this branch is
issue-3422-openapiplus one commit, so the diff shows #3471's changes too until #3471 merges (GitHub cannot base a goplus/builder PR on a fork branch). Review only the last commit (docs(openapi)!: course API contract release for course kinds). Do not merge before goplus/builder-backend#352 is deployed: this document describes the API only that release serves. Until then #3471 stays the accurate contract.What changes vs. #3471
Courseentrypoint/promptremoved.contentis nowoneOfGuidedCourseContent/PlaygroundCourseContent, selected bykind(theoneOfpromised in the #3471 review, now that the shape is final).POST /user/courseskindandcontentrequired; the transitional flat payload is no longer documented.PATCH /courses/{id}entrypoint/promptfields removed;contentis validated against the course's kind and replaced as a whole.POST /user/course-serieskindrequired (omitting it no longer meansguided).New component schemas:
GuidedCourseContent(entrypointnon-empty uri-reference,prompt≤ 12000 chars) andPlaygroundCourseContent(file collection mapping paths to universal URLs; may be empty so a course can be created before its files are uploaded). The copilot-context request keeps its own inline, non-empty file collection.Matches
docs/develop/tutorial-v2/module_CourseApis.ts(Course = GuidedCourse | PlaygroundCourse,CourseSeriesInputwith requiredkind). Verified by the goplus/builder-backend#352 rehearsal (see its description): the documented 400s and response shapes are what the Release 2 binary produces.