Versioned and unversioned APIs
Vendors version APIs inconsistently: path prefixes (/v1), headers (Accept: application/vnd...), separate hostnames, or no versioning at all. This page gives practical patterns for how to name and split dependencies in the Intello app.
Pattern A — version in the URL (preferred)
Example:
https://api.vendor.com/v1/openapi.jsonhttps://api.vendor.com/v2/openapi.json
Recommendation: create separate dependencies (or subscriptions) per major version. Benefits:
- Diffs stay scoped—you won’t mix v1 removals with v2 additions.
- Alert policies can treat v2 as critical while v1 is legacy sunset mode.
Pattern B — single spec, unstable servers / base path churn
Some vendors publish one OpenAPI file where internal routing churn looks like breaking changes but customer-facing stability is fine.
Mitigations:
- Use partial monitoring to only watch domains you integrate with.
- Pair Intello signal with vendor communications—sometimes noise is a hint the spec quality is low, not that your integration broke.
Pattern C — unversioned “living” document
The vendor updates the same URL in place. Intello handles this naturally: each poll snapshots whatever is current. Watch for:
- Large frequent diffs when vendors regenerate specs automatically.
- False breaking noise when tooling reorders schemas without semantic change—normalization helps but cannot fix all generators.
Pattern D — multiple specs per product surface
Some vendors ship openapi.yaml + internal.yaml or separate “public” vs “partner” bundles.
Recommendation: one Intello dependency per spec URL you actually ship code against—not every file the vendor publishes.
Choosing dependency names
Encode version and surface in name:
Stripe API 2023-10-16 (account)HubSpot CRM v3 (contacts)
This reduces confusion in Slack and PagerDuty titles.