Skip to content

docs(api): publish ServiceMap and RUM rule endpoints, fix reference drift - #246

Merged
ysyneu merged 2 commits into
feat/api-review-auto-fix-20260806from
docs/api-review-20260806
Aug 6, 2026
Merged

docs(api): publish ServiceMap and RUM rule endpoints, fix reference drift#246
ysyneu merged 2 commits into
feat/api-review-auto-fix-20260806from
docs/api-review-20260806

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Brings the public API reference back in line with what the services actually serve: 23 endpoints that were live but undocumented, one that was documented but dead, and five smaller mismatches.

New endpoints (23)

Group Count Endpoints
Monitors / Service map 5 status, topology, summary, fleet, fleet/summary
RUM / Error ingestion rules 8 list, create, update, delete, enable, disable, history/list, history/revert
RUM / Issue preset severity rules 9 the same eight plus reorder
RUM / Resources 1 resource/info

Notes worth a reviewer's eye:

  • ServiceMap is an optional subsystem — a deployment without its store configured answers ServiceUnavailable (503), which is documented per endpoint. at accepts only now and direction only outbound today; both are stated rather than presented as open enums.
  • reorder is a single-item move, not a swap or a full reordering: the dragged rule takes the target's priority and everything strictly between shifts by one.
  • history/revert answers InvalidParameter for an unknown version, not ResourceNotFound. This breaks the pattern the other rule-id operations follow, so it is called out on the page.
  • All 18 RUM endpoints carry no permission gate. Their pages therefore read "None — any valid app_key can call this operation", which is accurate: none of the API names appear as a factor on any permission point. Thirteen of them mutate rules. Flagging it here because publishing makes that gap visible; closing it is a backend change, not a docs one.

Removed (1)

POST /rum/facet/list had no backend route since the facet model was replaced by fields, and is no longer registered on the gateway — every documented call 404s. /rum/facet/count's usage note pointed readers at it and now points at /rum/field/list, its replacement.

Corrections (5)

  • /incident/work-item/list is no longer Pro-gated; the note is dropped. The work-item mutations stay Pro-gated.
  • /incident/comment-type/{create,update,delete,reorder} moved to the new Comment Types Manage permission — holding only Incidents Manage is rejected. The read path still accepts either.
  • /member/info/reset gains from, which marks an updated phone or email as verified when the account has member invites disabled, and now rejects an empty updates.
  • The consolidated specs were missing the AlertRule family's timezone property and the cron_pattern note about it, so a rule exported through them lost its timezone. Synced from the per-module spec.
  • Two endpoints had shipped without a catalog index entry (post-mortem content reset, on-call license list); rows added.

Plus one generator fix: a rate limit of one rendered as "1 requests/second".

Verification

Structural checks over all four surfaces that have to agree — the module spec Mintlify renders, the consolidated copy used for SDK and Apifox import, the docs.json nav allow-list, and the hand-maintained catalog:

  • 12 specs parse; EN/ZH operation sets and schema key sets are equal for every module.
  • Nav allow-list and specs agree in both directions, so nothing is published-but-invisible and nothing points at a missing page.
  • 654 catalog links compared against each operation's x-mint.href — zero mismatches.
  • Counts are self-consistent: 327 declared = 327 per-module sum = 327 table rows = 327 operations in the specs, in both languages.
  • No dangling $ref anywhere. Every new integer time field carries Unix in its description (seconds vs milliseconds distinguished), so the SDK generator maps them to a timestamp type rather than a bare int.

Reading the diff

The consolidated spec renders as 18 hunks with --diff-algorithm=histogram and 4174 with the default — deleting one path from the middle of a large uniform JSON confuses Myers badly. Real shape: 5031 insertions, 136 deletions, net +4895 lines.

ysyneu added 2 commits August 6, 2026 04:45
…rift

Publishes 23 endpoints and corrects five places where the reference no
longer matched how the service behaves.

New endpoints

- Monitors / Service map (5): status, topology, summary, fleet and
  fleet/summary. The subsystem is optional, so each page states that a
  deployment without the ServiceMap store configured answers
  ServiceUnavailable (503).
- RUM / Error ingestion rules (8) and Issue preset severity rules (9):
  list, create, update, delete, enable, disable, reorder (severity rules
  only) and the history list/revert pair.
- RUM / Resources (1): resource/info.

Corrections

- /incident/work-item/list no longer requires the On-call Pro license, so
  that note is dropped. The work-item mutations stay Pro-gated.
- /incident/comment-type/{create,update,delete,reorder} are gated by the
  new Comment Types Manage permission rather than Incidents Manage;
  holding only the latter is rejected. The read path is unaffected.
- /member/info/reset gains the `from` field, which marks an updated phone
  or email as verified when the account has member invites disabled, and
  now rejects an empty `updates` object.
- /rum/facet/list is removed. It has had no backend route since the facet
  model was replaced by fields, and it is no longer registered on the
  gateway, so every documented call 404s. The usage note on
  /rum/facet/count now points at /rum/field/list, its replacement.
- The consolidated specs were missing the AlertRule family's `timezone`
  property and the cron_pattern note that goes with it. Both are synced
  from the per-module spec so an exported rule keeps its timezone.

Also backfills two catalog rows for endpoints that shipped without an
index entry (post-mortem content reset, on-call license list), and stops
the generator emitting "1 requests/second" for a rate limit of one.

Review tip: the consolidated spec renders as 18 hunks with
`--diff-algorithm=histogram`, versus 4174 with the default.
- error-ingestion and preset-severity `rules/delete` said the rule stops being
  evaluated immediately. The enabled-rule set is cached for up to 5 seconds —
  the same lag already documented for enable/disable.
- preset-severity `rules/reorder` said only rules strictly between the two
  original positions shift. The target rule shifts as well.
- preset-severity `rules/history/list` said a snapshot is written before every
  update call. An update carrying none of the mutable fields writes none.
- preset-severity `rules/create` declared `minItems: 1` on `filters`, which the
  server does not enforce: an empty array is accepted and yields a rule that can
  never match. Drop the constraint and state the real behaviour instead.
- `resource/info` said `no_cache` recomputes the session usage counts. It
  bypasses the cache of the resource record; the counts come from a separate
  hourly cache the flag does not touch.
@ysyneu
ysyneu merged commit 974016d into feat/api-review-auto-fix-20260806 Aug 6, 2026
1 check passed
@ysyneu
ysyneu deleted the docs/api-review-20260806 branch August 6, 2026 14:20
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.

1 participant