[DX-144] Update control API spec for missing fields#3257
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughUpdated Control API docs link location and expanded the OpenAPI spec with new namespace configuration fields (mutableMessages, populateChannelRegistry, batchingPolicy, batchingConflationKey), exposeTimeSerial rename, and revocableTokens support on key schemas. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/pages/docs/platform/account/control-api.mdx`:
- Line 39: Replace the folder link "Ably OpenAPI Documents [GitHub
repository](https://github.com/ably/docs/tree/main/static/open-specs)" in the
paragraph mentioning the OpenAPI document with a direct link to the Control API
spec file named control-v1.yaml (the concrete raw spec URL used for Postman
import elsewhere in the doc); update the anchor so the text points to the exact
control-v1.yaml file (raw GitHub URL) and ensure the URL matches the Postman
import/raw spec URL referenced later to keep the canonical source consistent.
In `@static/open-specs/control-v1.yaml`:
- Around line 4903-4907: The schema permits mutableMessages: true without
requiring exposeTimeserial, which makes message interactions non-functional;
modify the three schema definitions (namespace_post, namespace_patch,
namespace_response) so that mutableMessages requires exposeTimeserial—either by
adding an if-then dependency (if properties.mutableMessages.const true then
require properties.exposeTimeserial.const true) or by adding dependentSchemas
enforcing this relationship, or alternatively update the descriptions for
mutableMessages in each schema to state explicitly that exposeTimeserial must
also be true when mutableMessages is enabled; update the same change in all
three places (namespace_post, namespace_patch, namespace_response).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: ca57e1b1-313f-4400-b947-1064f477a2fb
📒 Files selected for processing (2)
src/pages/docs/platform/account/control-api.mdxstatic/open-specs/control-v1.yaml
There was a problem hiding this comment.
Pull request overview
Updates the Control API OpenAPI spec to document newly supported namespace configuration fields and key capability options, and adjusts the Control API docs to point readers at the spec location.
Changes:
- Added namespace-level schema fields:
mutableMessages,populateChannelRegistry,batchingPolicy, andbatchingConflationKey(create/patch/response). - Added
revocableTokensto key schemas (create/patch/response). - Updated the Control API docs page link for where to find the OpenAPI document.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| static/open-specs/control-v1.yaml | Extends the Control API OpenAPI schemas with missing namespace and key fields. |
| src/pages/docs/platform/account/control-api.mdx | Updates the documentation link to the OpenAPI document location. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
sacOO7
force-pushed
the
fix/open-spec-control-api
branch
from
2d50b65 to
6820966
Compare
sacOO7
changed the title
sacOO7
force-pushed
the
fix/open-spec-control-api
branch
from
6820966 to
b11de6d
Compare
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
src/pages/docs/platform/account/control-api.mdx (1)
39-39: Use direct second-person wording here.This reads a bit passive and wordy for a docs page. A tighter rewrite keeps the same meaning and matches the repo doc style better.
✍️ Suggested wording
-The OpenAPI document for this API can be found in the Ably OpenAPI Documents [GitHub repository](https://github.com/ably/docs/tree/main/static/open-specs). It is not required in order to use Control API, but is provided to you so you may optionally generate your own documentation in the tool of your choice, or use mocking tools such as [Prism](https://stoplight.io/open-source/prism/) to assist in developing your clients. +You can find the OpenAPI document for this API in the Ably OpenAPI Documents [GitHub repository](https://github.com/ably/docs/tree/main/static/open-specs). You do not need it to use the Control API, but you can use it to generate documentation in the tool of your choice or mock clients with tools such as [Prism](https://stoplight.io/open-source/prism/).As per coding guidelines: "Write documentation using International English with US spelling, present tense, active voice, and second person perspective."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/pages/docs/platform/account/control-api.mdx` at line 39, Replace the passive, wordy sentence starting "The OpenAPI document for this API can be found in the Ably OpenAPI Documents [GitHub repository]..." with a concise, direct second-person active construction; e.g. "You can find the OpenAPI document in the Ably OpenAPI Documents GitHub repository. You don’t need it to use the Control API, but you can use it to generate docs or mock endpoints with tools like Prism." Ensure US spelling, present tense, active voice, and keep the meaning the same.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@static/open-specs/control-v1.yaml`:
- Around line 4900-4903: The spec incorrectly renamed the field exposeTimeserial
to exposeTimeSerial; revert the property name back to exposeTimeserial in the
namespace schemas (e.g., namespace_post, namespace_patch, namespace_response) so
generated clients match the existing Control API wire name, and ensure you do
not couple it to mutableMessages (leave mutableMessages as an independent
boolean); update all occurrences (including the other places noted) to use
exposeTimeserial.
- Around line 4923-4934: The OpenAPI schema uses JSON Schema conditional
keywords (if/then/const) for the invariant between properties mutableMessages
and persisted; these are not valid in OpenAPI 3.0.1. Either change the document
version to OpenAPI 3.1 so conditional keywords are supported, or remove the
if/then/const blocks and instead document the invariant in the Schema Object
descriptions (e.g., in the description fields for the object or for properties
mutableMessages and persisted) and any external comments/readme; locate the
conditional blocks by searching for the properties named mutableMessages and
persisted (the three occurrences that contain if/then/const) and apply the
chosen remediation consistently to all three places.
---
Nitpick comments:
In `@src/pages/docs/platform/account/control-api.mdx`:
- Line 39: Replace the passive, wordy sentence starting "The OpenAPI document
for this API can be found in the Ably OpenAPI Documents [GitHub repository]..."
with a concise, direct second-person active construction; e.g. "You can find the
OpenAPI document in the Ably OpenAPI Documents GitHub repository. You don’t need
it to use the Control API, but you can use it to generate docs or mock endpoints
with tools like Prism." Ensure US spelling, present tense, active voice, and
keep the meaning the same.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 1d3e61dd-0191-45c7-af08-63709c350685
📒 Files selected for processing (2)
src/pages/docs/platform/account/control-api.mdxstatic/open-specs/control-v1.yaml
sacOO7
force-pushed
the
fix/open-spec-control-api
branch
from
b11de6d to
c750707
Compare
sacOO7
force-pushed
the
fix/open-spec-control-api
branch
from
c750707 to
6a55eb8
Compare
mutableMessages,batchingPolicy,batchingConflationKeyetcTODOs
src/pages/docs/platform/account/control-api.mdxfor newly added fieldsSummary by CodeRabbit
Documentation
New Features