Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions plugins/openapi/adapter/convex.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ import (
// Variables, not constants, only so tests can point them at a local server.
var (
// convexCommitsURL lists the commits that changed the Deployment API
// spec in get-convex/convex-backend, newest first; with per_page=1, the
// spec in convex/convex-backend, newest first; with per_page=1, the
// newest.
convexCommitsURL = "https://api.github.com/repos/get-convex/convex-backend/commits?path=npm-packages/@convex-dev/platform/deployment-openapi.json&per_page=1"
convexCommitsURL = "https://api.github.com/repos/convex/convex-backend/commits?path=npm-packages/@convex-dev/platform/deployment-openapi.json&per_page=1"
// convexCommitURL is one commit, for its date.
convexCommitURL = "https://api.github.com/repos/get-convex/convex-backend/commits/%s"
convexCommitURL = "https://api.github.com/repos/convex/convex-backend/commits/%s"
// convexSpecURLTemplate is the Deployment API spec at one commit: 68
// commits from 2025-08-19 to 2026-11-16 (checked 2026-11-19), and a
// commit never changes.
convexSpecURLTemplate = "https://raw.githubusercontent.com/get-convex/convex-backend/%s/npm-packages/@convex-dev/platform/deployment-openapi.json"
convexSpecURLTemplate = "https://raw.githubusercontent.com/convex/convex-backend/%s/npm-packages/@convex-dev/platform/deployment-openapi.json"
)

// Convex adapts the Convex Deployment API spec (`{deployment-url}/api/v1`)
// in get-convex/convex-backend for the openapi plugin. A tag here is the
// in convex/convex-backend for the openapi plugin. A tag here is the
// commit that last changed the spec, as for Supabase.
//
// The repo does tag releases, `precompiled-YYYY-MM-DD-<sha>` (1,213 of
Expand Down
2 changes: 1 addition & 1 deletion plugins/openapi/adapter/versions.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ func (Neon) Versions(ctx context.Context) ([]plugin.Version, error) {

// Versions are the commits that changed Convex's deployment API spec.
func (Convex) Versions(ctx context.Context) ([]plugin.Version, error) {
return commits(ctx, "get-convex/convex-backend", "npm-packages/@convex-dev/platform/deployment-openapi.json")
return commits(ctx, "convex/convex-backend", "npm-packages/@convex-dev/platform/deployment-openapi.json")
}

// Versions are the commits that changed PlanetScale's spec.
Expand Down
2 changes: 1 addition & 1 deletion plugins/openapi/convex_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ func (fakeConvexAdapter) SourcePointer(content []byte) func(string) string {
func convexFile(tag string) string { return "testdata/convex-" + tag + ".json" }

func convexURL(tag string) string {
return "https://raw.githubusercontent.com/get-convex/convex-backend/" + convexCommits[tag][0] + "/npm-packages/@convex-dev/platform/deployment-openapi.json"
return "https://raw.githubusercontent.com/convex/convex-backend/" + convexCommits[tag][0] + "/npm-packages/@convex-dev/platform/deployment-openapi.json"
}

// convexPlugin is the plugin exactly as registered, over the saved copies.
Expand Down
2 changes: 1 addition & 1 deletion plugins/openapi/openapi.go
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ func init() {
Sources: []plugin.Source{{
ID: "deployment-api", Layer: plugin.LayerAPI, Page: "providers/convex.md",
Watches: "Deployment API operations deprecated, and deprecated operations removed, between commits of the spec",
URLs: []string{"https://github.com/get-convex/convex-backend"},
URLs: []string{"https://github.com/convex/convex-backend"},
Plugin: Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep},
}},
})
Expand Down
4 changes: 2 additions & 2 deletions plugins/openapi/testdata/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ Each pair is a real breaking change between two releases of a provider's own spe
| `neon-5c57d009.json`, `neon-93b93dc9.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/5c57d0095a9a4594a3c8b09d499b132902e7c42e/packages/sdk/spec/neon-openapi.json (and `93b93dc9e4d1b4ab48dac6c8ccba76b35541b476`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | "Deprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`" (`POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email`, new in `93b93dc9`) |
| `neon-4c6b3be4.json`, `neon-4497de89.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/4c6b3be46b1b333e7f910db51218ad144de27179/packages/sdk/spec/neon-openapi.json (and `4497de89a5e84b38956fde686d271f99317b8fdb`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | `"/projects/{project_id}/branches/{branch_id}/recover": {` (in `4c6b3be4`, gone in `4497de89` without being deprecated): the drop test |
| `neon-api-client-2.7.2.yaml`, `neon-api-client-2.7.3.yaml` | `public-v2-for-users.gen.yaml` in https://registry.npmjs.org/@neondatabase/api-client/-/api-client-2.7.2.tgz (and `api-client-2.7.3.tgz`) | 2026-11-19 | Excerpt for testing; © Neon. The package is MIT, but the spec's own `info.license` says "Proprietary" | "**Deprecated.** Use `GET /consumption_history/projects` (`getConsumptionHistoryPerProject`)" (`GET /consumption_history/account`, in 2.7.2, gone in 2.7.3) |
| `convex-f35879bb.json`, `convex-5e5159cb.json` | https://raw.githubusercontent.com/get-convex/convex-backend/f35879bb396491942bf8ecbc8ef5e4280499f89f/npm-packages/@convex-dev/platform/deployment-openapi.json (and `5e5159cbea5188e9da5400febda1b031a233eea0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, and five more log stream operations, new in `5e5159cb`) |
| `convex-3f6edf7a.json`, `convex-3ead9091.json` | https://raw.githubusercontent.com/get-convex/convex-backend/3f6edf7ab8f3f98e027f317633246a19348eabcc/npm-packages/@convex-dev/platform/deployment-openapi.json (and `3ead909103b7f5897f529c031e80991ad174b07e`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | `"name": {` in `UsageLimitConfigRequest` and `UsageLimitConfigResponse` (in `3f6edf7a`, gone in `3ead9091` without being deprecated): the drop test |
| `convex-f35879bb.json`, `convex-5e5159cb.json` | https://raw.githubusercontent.com/convex/convex-backend/f35879bb396491942bf8ecbc8ef5e4280499f89f/npm-packages/@convex-dev/platform/deployment-openapi.json (and `5e5159cbea5188e9da5400febda1b031a233eea0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, and five more log stream operations, new in `5e5159cb`) |
| `convex-3f6edf7a.json`, `convex-3ead9091.json` | https://raw.githubusercontent.com/convex/convex-backend/3f6edf7ab8f3f98e027f317633246a19348eabcc/npm-packages/@convex-dev/platform/deployment-openapi.json (and `3ead909103b7f5897f529c031e80991ad174b07e`) | 2026-11-19 | FSL-1.1-Apache-2.0 (convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | `"name": {` in `UsageLimitConfigRequest` and `UsageLimitConfigResponse` (in `3f6edf7a`, gone in `3ead9091` without being deprecated): the drop test |
| `planetscale-e631095a.yaml`, `planetscale-fc13e09d.yaml` | https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/e631095aa649a6797578a1d51d861b91e0568aa1/schemas/openapi.yaml (and `fc13e09d0c18b893aabd3e02d175d13957bba677`) | 2026-11-19 | none stated for the file (its `info` says "&copy; 2026 PlanetScale, Inc."); the repo, planetscale/terraform-provider-planetscale, is Apache-2.0. Excerpt for testing; © PlanetScale | "Deprecated. Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests instead." (`GET .../neki-changes`, new in `fc13e09d`) |
| `planetscale-b49c3540.yaml`, `planetscale-f6d6ad4d.yaml` | https://raw.githubusercontent.com/planetscale/terraform-provider-planetscale/b49c354080667638b79781801f0517ae07bc55b8/schemas/openapi.yaml (and `f6d6ad4d3929f6c1ef021eb13c1541ba31f72107`) | 2026-11-19 | none stated for the file (its `info` says "&copy; 2026 PlanetScale, Inc."); the repo, planetscale/terraform-provider-planetscale, is Apache-2.0. Excerpt for testing; © PlanetScale | `/organizations/{organization}/databases/{database}/branches/{branch}/read-only-replicas:` (in `b49c3540`, never deprecated, gone in `f6d6ad4d`, where `.../dedicated-read-replicas:` is): the drop test |
| `appwrite-1.9.x-8c00ba35-server.json`, `appwrite-1.9.x-7d74bf9f-server.json` | https://raw.githubusercontent.com/appwrite/specs/8c00ba356b01d43fbc6c88c60fb2a4fc99e04b40/specs/1.9.x/open-api3-1.9.x-server.json (and `7d74bf9f3c0c990745e822f5935bcfaca310fd06`) | 2026-11-19 | BSD-3-Clause (appwrite/specs) | `"replaceWith": "tablesDB.createTransaction"` (`x-appwrite.deprecated` of `POST /databases/transactions`, flagged in `7d74bf9f` with 13 more) |
Expand Down
12 changes: 6 additions & 6 deletions plugins/openapi/testdata/golden/convex.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"operation": "POST /api/v1/create_log_stream"
},
"description": "Operation POST /api/v1/create_log_stream marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1create_log_stream/post",
"source_excerpt": "{\"deprecated\":true,\"description\":\"Create a new log stream for the deployment. Errors if a log stream of the\\ngiven type already exists.\\n\\nDeprecated: use `POST /integrations` instead.\",\"operationId\":\"create_log_stream\",\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Create log stream\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand All @@ -35,7 +35,7 @@
"operation": "POST /api/v1/delete_log_stream/{id}"
},
"description": "Operation POST /api/v1/delete_log_stream/{id} marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1delete_log_stream~1{id}/post",
"source_excerpt": "{\"deprecated\":true,\"description\":\"Delete the deployment's log stream with the given id.\\n\\nDeprecated: use `DELETE /integrations/{id}` instead.\",\"operationId\":\"delete_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to delete\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Delete log stream\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand All @@ -56,7 +56,7 @@
"operation": "GET /api/v1/get_log_stream/{id}"
},
"description": "Operation GET /api/v1/get_log_stream/{id} marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1get_log_stream~1{id}/get",
"source_excerpt": "{\"deprecated\":true,\"description\":\"Get the config for a specific log stream by id.\\n\\nDeprecated: use `GET /integrations/{id}` instead.\",\"operationId\":\"get_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to retrieve\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Get log stream\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand All @@ -77,7 +77,7 @@
"operation": "GET /api/v1/list_log_streams"
},
"description": "Operation GET /api/v1/list_log_streams marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1list_log_streams/get",
"source_excerpt": "{\"deprecated\":true,\"description\":\"List configs for all existing log streams in a deployment.\\n\\nDeprecated: use `GET /integrations` instead.\",\"operationId\":\"list_log_streams\",\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"items\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"},\"type\":\"array\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"List log streams\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand All @@ -98,7 +98,7 @@
"operation": "POST /api/v1/rotate_webhook_secret/{id}"
},
"description": "Operation POST /api/v1/rotate_webhook_secret/{id} marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1rotate_webhook_secret~1{id}/post",
"source_excerpt": "{\"deprecated\":true,\"description\":\"Rotate the secret for the webhook log stream.\\n\\nDeprecated: use `POST /integrations/{id}/rotate_webhook_secret` instead.\",\"operationId\":\"rotate_webhook_secret\",\"parameters\":[{\"description\":\"id of the webhook log stream for which to rotate the secret\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/RotateLogStreamSecretResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Rotate webhook log stream secret\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand All @@ -119,7 +119,7 @@
"operation": "POST /api/v1/update_log_stream/{id}"
},
"description": "Operation POST /api/v1/update_log_stream/{id} marked deprecated.",
"source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_url": "https://raw.githubusercontent.com/convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json",
"source_pointer": "/paths/~1update_log_stream~1{id}/post",
"source_excerpt": "{\"deprecated\":true,\"description\":\"Update an existing log stream for the deployment. Omit a field to keep the\\nexisting value, and use `null` to unset a field.\\n\\nDeprecated: use `PATCH /integrations/{id}` instead.\",\"operationId\":\"update_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to update\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Update log stream\",\"tags\":[\"Log Streams\"]}",
"confidence": 1,
Expand Down
4 changes: 2 additions & 2 deletions providers/convex.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ Kind: `openapi` (`plugins/openapi`), with `adapter.Convex`.

## Why this source

- **Source:** `npm-packages/@convex-dev/platform/deployment-openapi.json` in [get-convex/convex-backend](https://github.com/get-convex/convex-backend), pinned to the commit that last changed it (`https://raw.githubusercontent.com/get-convex/convex-backend/<sha>/npm-packages/@convex-dev/platform/deployment-openapi.json`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19.
- **Source:** `npm-packages/@convex-dev/platform/deployment-openapi.json` in [convex/convex-backend](https://github.com/convex/convex-backend) (the org was `get-convex` until 2026; GitHub redirects the old URLs, checked 2026-11-20), pinned to the commit that last changed it (`https://raw.githubusercontent.com/convex/convex-backend/<sha>/npm-packages/@convex-dev/platform/deployment-openapi.json`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19.
- **Why a commit, not a release tag:** the repo tags `precompiled-YYYY-MM-DD-<sha>` builds (1,213 of them), but those are daily builds of the self-hosted backend, not releases of the API. There are several on some days, ordered only by commit date, and the spec is the same in most of them. The spec at a tag is the spec at the last commit before it that changed the file, so the commits see every version a tag would, and finding the newest takes one call instead of paging through the tags. A commit never changes, so it can be cited and replayed.
- **Why this one:**
- It's Convex's own description of the API: its docs build renders the API reference from it.
- It marks deprecations with the `deprecated` flag and says what to use instead ("Deprecated: use `GET /integrations` instead."). Convex's docs build drops flagged operations, "since they stay served only for existing callers" (`npm-packages/docs/scripts/prepare-openapi-specs.js`).
- There are 68 versions from 2025-08-19, when the spec was added, to 2026-11-16.
- **Alternatives considered:**
- **The Management API spec** (`management-openapi.json`, next to it: teams, projects, deployments). Its `info.license` is `LicenseRef-Convex`, which nothing in the repo defines, so the plugin neither reads nor saves it.
- **The SDK changelogs** (`convex` on npm, `get-convex/convex-js` `CHANGELOG.md`; `convex-py`). One flat list of bullets per version (95 versions in `convex-js`), with no removed or deprecated sections for the `changelog` plugin to read.
- **The SDK changelogs** (`convex` on npm, `convex/convex-js` `CHANGELOG.md`; `convex-py`). One flat list of bullets per version (95 versions in `convex-js`), with no removed or deprecated sections for the `changelog` plugin to read.
- **[Convex News](https://news.convex.dev/)** (RSS at `https://news.convex.dev/rss/`). Product news and announcements, newest post 2026-09-21; it doesn't name API operations.
- **The `@convex-dev/platform` npm package** (0.1.11). Its tarball has only `package.json` and the generated client, not the specs.
- **Quote:** "Deprecated: use `GET /integrations` instead." (`GET /api/v1/list_log_streams`, deprecated in the spec on 2026-11-05)
Expand Down
Loading