docs(api-spec): switch update endpoints to PATCH semantics

[aofei]

• Change PUT to PATCH for user, project, asset, course, and course-series update endpoints in docs/openapi.yaml
• Replace required request fields with minProperties: 1 on all updated bodies so clients can send partial updates without breaking schema validation
• Keep response schemas and endpoint paths unchanged to align with API docs only

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request updates the API documentation to reflect more appropriate HTTP semantics for update operations. By transitioning from PUT to PATCH and adjusting request body schemas, the API now explicitly supports partial updates, offering greater flexibility for clients interacting with user, project, asset, course, and course-series resources. The changes are confined to the OpenAPI specification, ensuring no impact on existing API implementations.

Highlights

• API Endpoint Semantics: Switched PUT HTTP methods to PATCH for user, project, asset, course, and course-series update endpoints in the OpenAPI specification.
• Partial Update Support: Replaced explicit required fields with minProperties: 1 in the request bodies for update operations, enabling clients to send partial updates without schema validation failures.
• Documentation Alignment: Ensured that response schemas and endpoint paths remain unchanged to align with API documentation only, without altering the underlying API behavior.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/openapi.yaml
  • Changed HTTP method from put to patch for the authenticated user update endpoint.
  • Changed HTTP method from put to patch for the project update endpoint.
  • Replaced required fields with minProperties: 1 in the project update request body schema.
  • Changed HTTP method from put to patch for the asset update endpoint.
  • Replaced required fields with minProperties: 1 in the asset update request body schema.
  • Changed HTTP method from put to patch for the course update endpoint.
  • Replaced required fields with minProperties: 1 in the course update request body schema.
  • Changed HTTP method from put to patch for the course series update endpoint.
  • Replaced required fields with minProperties: 1 in the course series update request body schema.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly updates the OpenAPI specification to use PATCH instead of PUT for several update endpoints, which is a good semantic change for partial updates.

However, this is a breaking API change, and the PR is critically incomplete because the client-side code that consumes these endpoints has not been updated. This will cause all update functionality to fail once the backend implements these changes.

The following changes are required:

1. A patch method needs to be added to the Client class in spx-gui/src/apis/common/client.ts. It can be implemented similarly to the existing put method.
2. All update... functions in the spx-gui/src/apis/ directory that correspond to the changed endpoints must be updated to use client.patch instead of client.put. This affects user.ts, project.ts, asset.ts, course.ts, and course-series.ts.

I have added comments on each affected endpoint in docs/openapi.yaml to point to the specific client-side function that needs to be updated.

[Copilot]

Pull request overview

Updates the OpenAPI specification to document partial-update semantics for several “update” endpoints by switching from PUT to PATCH and loosening request-body required fields. This is intended to allow clients to send partial updates without failing schema validation.

Changes:

• Switch update operations for user, project, asset, course, and course-series endpoints from put to patch.
• Replace required: [...] request-body constraints with minProperties: 1 to permit partial update payloads.
• Keep paths and response schemas unchanged.

Comments suppressed due to low confidence (5)

docs/openapi.yaml:823

• This operation is now documented as PATCH, but the GUI client currently uses PUT /asset/{id} (spx-gui/src/apis/asset.ts). If PATCH is intended, the client (and backend, if applicable) should be updated, otherwise keep put (or list both) to match deployed behavior.

    patch:
      tags:
        - Assets
      summary: Update an asset
      description: |

docs/openapi.yaml:1011

• This operation is now documented as PATCH, but the GUI client currently uses PUT /course/{id} (spx-gui/src/apis/course.ts). Please align the OpenAPI method with the actually supported API method(s) so generated clients and docs don’t diverge.

    patch:
      tags:
        - Courses
      summary: Update a course
      description: |

docs/openapi.yaml:1192

• This operation is now documented as PATCH, but the GUI client currently uses PUT /course-series/{id} (spx-gui/src/apis/course-series.ts). If PATCH is the new contract, consider updating existing clients or documenting both methods for compatibility.

    patch:
      tags:
        - Course Series
      summary: Update a course series
      description: |

docs/openapi.yaml:103

• The spec switches this endpoint to PATCH, but the existing GUI client still calls PUT /user (see spx-gui/src/apis/user.ts). If the server still expects PUT, this OpenAPI change will be incorrect for consumers; consider documenting both put and patch during a transition or updating the client/backend in the same change set.

    patch:
      tags:
        - Users
      summary: Update the authenticated user
      description: Update the profile information of the authenticated user.

docs/openapi.yaml:381

• This operation is now documented as PATCH, but the GUI client currently uses PUT /project/{owner}/{name} (spx-gui/src/apis/project.ts). Please ensure the backend actually supports PATCH (or document both methods) to avoid a spec/client mismatch.

    patch:
      tags:
        - Projects
      summary: Update a project
      description: Update the details of a specific project.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fennoai]

Clean, focused change that correctly aligns the API spec with partial-update semantics. The two noteworthy points are:

1. minProperties: 1 vs. anyOf — without additionalProperties: false, the constraint is satisfied by unknown keys, so it doesn't truly guarantee a meaningful field was sent. See inline comment.
2. Missing PATCH semantics in description fields — all five endpoints still describe a generic update; a note that omitted fields are preserved would make the contract explicit for consumers. See inline comment.