Skip to content

docs(standards): don't append "API" to OpenAPI spec titles #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaelelrom merged 1 commit into from
Aug 17, 2026
Merged

docs(standards): don't append "API" to OpenAPI spec titles #77

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions STANDARDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Imported into Itential Platform as Integration Models.
- To mark a spec as the actively-maintained, most current one, overwrite `info.version` to `"latest"` and rename the file to match (e.g., `cisco_meraki_dashboard-latest.json`). Since this overwrites the vendor's real version number, preserve it in an `x-vendor-api-version` field (e.g., `"x-vendor-api-version": "1.48.0"`) so it isn't lost — see any existing `-latest.json` spec for an example.
- Never use an underscore in place of the separating hyphen (e.g., `meraki_1.48.0.json` is incorrect; `meraki-1.48.0.json` is correct).
- `info.title` must contain only the integration name — no version numbers (e.g., `Cisco Meraki Dashboard`, not `Cisco Meraki Dashboard v1.48`).
- **Don't append "API" to `info.title`** — every asset here is an API, so it's redundant (e.g., `Zscaler Internet Access`, not `Zscaler Internet Access API`; `Akamai Edge DNS`, not `Akamai Edge DNS API`). Also drop redundant product-line abbreviations already spelled out earlier in the title (e.g., `Zscaler Internet Access`, not `Zscaler Internet Access (ZIA) API`).
- `info.version` must reflect the actual API version (use `"latest"` to match a `-latest.json` filename).
- **Slim the `-latest` spec to common CRUD for automation**: A vendor's full published spec is often far larger than anything Itential Platform automation actually needs. The `-latest.json` file should be a curated subset — keep the core create/read/update/delete operations and resources someone would realistically automate, and drop long tails like device-type/config templates, modular-hardware sub-resources, the vendor's own internal tooling (scripts, webhooks, job/task management, user/permission administration), health/heartbeat/metrics/self-introspection endpoints, and other niche feature areas. Go operation-by-operation — a small, already-narrow vendor API can still have a handful of non-automation plumbing endpoints mixed in; don't skip the review just because the spec looks small. When you slim a spec, keep the full original as its own dated `{title}-{version}.json` file (per the version-labeling rule above) so nothing is lost — the `-latest.json` is a derived copy, not a replacement, even in the case below where nothing ends up excluded. Document what's included/excluded in the product's `README.md` (list the kept resources by category so it's scannable — see NetBox's `README.md` for the pattern). `-latest` should always read as the deliberately-curated automation spec — never label it "full" or "untouched" in the README, even when a review finds nothing to cut.
- `info.description` is shown in the Itential Platform GUI — keep it a normal, concise vendor/product description. Don't put curation notes there, and don't repeat boilerplate across specs.
Expand Down
Loading