diff --git a/STANDARDS.md b/STANDARDS.md index 2386499..792be89 100644 --- a/STANDARDS.md +++ b/STANDARDS.md @@ -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.