Repository navigation
docs(api-reference): align the API reference with server behavior - #1068
Merged
Merged
Conversation
- Quick start: document the Fd-App-Key header, response language
(locale / lang / Accept-Language), that data is {} or omitted when an
operation has no payload, and the timestamp/enum/update conventions.
Move limits and errors to one page instead of repeating them.
- Rate limits and errors: state the default per-account limits (read
50/s and 1,000/min, write 20/s and 300/min), the
Flashcat-Request-Rate-Limit-Delay header on 429, and a corrected error
code table (MethodNotAllowed is 405, ResourceNotFound means the object
does not exist, NoLicense covers plan, quota and credits).
- Pagination: limits and defaults vary per operation; list every
operation that accepts search_after_ctx; explain that on incident and
alert lists has_next_page stops at 1,000 items in page-number mode and
how to continue with the cursor.
- Point the Go SDK pages at the new error code anchor.
Review all 370 public operations against the backend implementation and
fix what a caller needs to use each endpoint from its page alone:
- Restrictions: rate limits now match the gateway (most write operations
are 300/min and 20/s, not the read tier), permissions list every
permission that grants the call, and audit and plan requirements are
stated where they apply.
- Enums: declare the full value set for status, type, mode and similar
fields and explain each value; open sets say so.
- Request and response schemas: add missing fields, remove fields the
server no longer accepts or returns, correct required lists, mark
fields that can be null, and state units (seconds, milliseconds,
nanoseconds) and defaults.
- Usage notes: correct behavior that was described wrongly (whole-object
replacement on several upserts, soft vs permanent deletes, inhibit rule
semantics, pagination limits) and move long descriptions out of the
page subtitle.
- Examples: every request and 200 response example validates against its
schema; operations without a payload show no data field.
- Shared components: data is optional in the success envelope, 403 is
documented on every operation, 429 documents the
Flashcat-Request-Rate-Limit-Delay header, the error code table matches
the server, and the APP Key scheme mentions the Fd-App-Key header.
- API catalog: add the five missing monitor folder operations (370 total).
- Rebuild the consolidated openapi.{en,zh}.json from the module specs.
Add five rules: integer enums must explain every value, required may only name declared properties, every operation documents 403, request and 200 response examples must match their schema, and operation descriptions stay within 220 characters.
ysyneu
added a commit
that referenced
this pull request
Oct 17, 2026
Conflicts in the OpenAPI introduction, pagination, catalog and Go SDK pages resolve to #1068's text, which already links to rate limits and describes pagination by behavior. The catalog total is 372: the 370 endpoints with reference pages plus gallery pin/unpin, matching the per-module counts.
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.
Summary
Brings the public API reference in line with what the server actually does, so a caller can use each endpoint from its page alone.
Conventions pages (
openapi/introduction,rate-limits,pagination, zh + en)Fd-App-Keyheader, response language (locale/lang/Accept-Language), and that operations without a payload returndata: {}or omitdata.Flashcat-Request-Rate-Limit-Delayheader on 429.MethodNotAllowedis 405;ResourceNotFoundmeans the object does not exist;NoLicensecovers plan, quota and credits) and keep it in one place instead of two.search_after_ctx; on List incidents / List alerts,has_next_pagestops at 1,000 items in page-number mode, so use the cursor beyond that.All 370 operations (per-module specs + consolidated copies)
requiredand nullability fixed, units and defaults stated.Lint gate (
scripts/lint_openapi.py): five new rules — integer enums explained,required⊆ declared properties, 403 on every operation, examples match their schema, operation description ≤ 220 chars.Checks run
python3 scripts/lint_openapi.py→ no violations (the new rules flag 305 missing 403s, 95 example mismatches and 12 long descriptions on the previous specs).python3 scripts/api_path_redirects.py --check→ pass.$ref, consolidated files equal the module files, 370 operations = docs.json nav = both API catalogs.mint broken-linksnot run (does not converge locally); worth a check after merge.