api-contract-docs

Name: api-contract-docs
Author: pricewatcha

When changing the public API contract, update docs and both OpenAPI specs

by pricewatcha(0) 0 installs

Free

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Instruction file imported from pricewatcha/pricewatcha-api (.cursor/rules/api-contract-docs.mdc). Copyright stays with the author.

Public API contract updates

Canonical guides live in docs/. Do not edit README.md by hand.

After any semantic change to endpoints, query params, or response fields:

Edit the matching file under docs/ (and docs/changelog.md).
Run python scripts/build_readme.py.
Update openapi/openapi.yaml (GitHub contract). Query params need a description.
Update ../price_tracker/app/api/v1/openapi_spec.py (live GET /openapi.json).
Run ../price_tracker/scripts/sync_api_docs.sh and commit app/api_docs/.
If an MCP tool is affected: mcp-server/src/tools/*.ts and mcp/tools.schema.json.

Checks: python scripts/build_readme.py --check and python scripts/verify_openapi_query_descriptions.py.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

# after Install: the listing is in your workspace's routing pool - a plan picks it for its slot
curl -s -X POST https://api.opensmartroute.ai/api/v1/route -H 'Authorization: Bearer $OSR_API_KEY' -H 'Content-Type: application/json' -d '{"text": "...", "plan": true}'

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

pricewatcha-pricewatcha-api-api-contract-docs-rule.ocm.jsonjson

{
  "ocm": "1",
  "id": "pricewatcha-pricewatcha-api-api-contract-docs-rule",
  "kind": "skill",
  "name": "api-contract-docs",
  "description": "When changing the public API contract, update docs and both OpenAPI specs",
  "publisher": "pricewatcha",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "legal"
    ],
    "tags": [
      "skill-md",
      "github-cursor-rules"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "When changing the public API contract, update docs and both OpenAPI specs"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github-cursor-rules",
      "repository": "https://github.com/pricewatcha/pricewatcha-api",
      "path": ".cursor/rules/api-contract-docs.mdc",
      "ref": "da67edd947d852628c1291790ff78995a1fc170c",
      "url": "https://github.com/pricewatcha/pricewatcha-api/blob/da67edd947d852628c1291790ff78995a1fc170c/.cursor/rules/api-contract-docs.mdc",
      "key": "pricewatcha/pricewatcha-api/.cursor/rules/api-contract-docs.mdc"
    },
    "applies_to": "docs/**/*.md,openapi/**/*.yaml,mcp-server/src/tools/**/*.ts,mcp/tools.schema.json"
  },
  "instructions": "# Public API contract updates\n\nCanonical guides live in `docs/`. Do not edit `README.md` by hand.\n\nAfter any semantic change to endpoints, query params, or response fields:\n\n1. Edit the matching file under `docs/` (and `docs/changelog.md`).\n2. Run `python scripts/build_readme.py`.\n3. Update **`openapi/openapi.yaml`** (GitHub contract). Query params need a `description`.\n4. Update **`../price_tracker/app/api/v1/openapi_spec.py`** (live `GET /openapi.json`).\n5. Run `../price_tracker/scripts/sync_api_docs.sh` and commit `app/api_docs/`.\n6. If an MCP tool is affected: `mcp-server/src/tools/*.ts` a",
  "cost": {
    "context_tokens": 184
  }
}

Fetch it by URL: GET /api/v1/registry/pricewatcha-pricewatcha-api-api-contract-docs-rule/manifest?version=1.0.0

About

Public API contract updates

Use it

Manifest

Reviews