Summary
Customer Phil Goodrich (Pro) reported a versioning-hygiene gap in docs.sharpapi.io/openapi.json and asked whether SharpAPI will commit to bumping info.version on path/schema changes going forward, so consumer-side change detection becomes feasible.
This is the policy / process companion to #230 (which fixes the immediate /account shape divergence + bumps the version once). #230 closes the specific divergence; this issue tracks the systemic commitment that prevents the next one.
What Phil observed
Comparing the locked copy of docs.sharpapi.io/openapi.json we have on file from a prior fetch against today's fetch, the vendor doc has REMOVED two paths (/sports/{sportId} and /sportsbooks/{bookId}) but info.version remained at 2.0.0. Path-level changes typically warrant a minor-version bump. This makes consumer-side change detection difficult — we cannot programmatically detect that the spec changed without doing a sha256 of the entire file.
Going forward, will SharpAPI commit to bumping info.version in the OpenAPI spec when paths or schemas change, so consumers can detect changes via header/version polling?
Proposed scope
- Policy: every change to
openapi.json that adds / removes paths or modifies response schemas bumps info.version per SemVer (MAJOR for breaking schema changes, MINOR for new paths/fields, PATCH for description-only edits or doc clarifications).
- Mechanism: a CI check on this repo that fails if
info.version is unchanged across a PR that modifies paths.* or schema definitions.
- Consumer signal: add an
X-OpenAPI-Version HTTP response header (or include info.version in /account response under meta.openapi_version) so customers polling without re-downloading the full spec can detect change.
- Optional: publish a
CHANGELOG.md in this repo with one line per version bump linking the changing PR.
Acceptance
- Documented policy in
docs.sharpapi.io/CONTRIBUTING.md or README.md covering when to bump and how
- CI check live + enforced on PRs
- Either response header OR spec-version field in a customer-readable endpoint
- Changelog or some other public way to inspect history of version bumps
Related
Why this matters beyond Phil
Other API customers in similar integration patterns (CI-graded API contract testing, schema-pinned clients) hit the same observable. The cost of the policy + mechanism is small; the cost of the next surprise divergence to a paying integration partner is large.
Summary
Customer Phil Goodrich (Pro) reported a versioning-hygiene gap in
docs.sharpapi.io/openapi.jsonand asked whether SharpAPI will commit to bumpinginfo.versionon path/schema changes going forward, so consumer-side change detection becomes feasible.This is the policy / process companion to #230 (which fixes the immediate
/accountshape divergence + bumps the version once). #230 closes the specific divergence; this issue tracks the systemic commitment that prevents the next one.What Phil observed
Proposed scope
openapi.jsonthat adds / removes paths or modifies response schemas bumpsinfo.versionper SemVer (MAJORfor breaking schema changes,MINORfor new paths/fields,PATCHfor description-only edits or doc clarifications).info.versionis unchanged across a PR that modifiespaths.*or schema definitions.X-OpenAPI-VersionHTTP response header (or includeinfo.versionin/accountresponse undermeta.openapi_version) so customers polling without re-downloading the full spec can detect change.CHANGELOG.mdin this repo with one line per version bump linking the changing PR.Acceptance
docs.sharpapi.io/CONTRIBUTING.mdorREADME.mdcovering when to bump and howRelated
/accountdivergence + the initial version bumpWhy this matters beyond Phil
Other API customers in similar integration patterns (CI-graded API contract testing, schema-pinned clients) hit the same observable. The cost of the policy + mechanism is small; the cost of the next surprise divergence to a paying integration partner is large.