Skip to content

Remove SDK calls that request paths the API doesn't route - #135

Open
lelia wants to merge 10 commits into
mainfrom
lelia/prune-unrouted-sdk-calls
Open

lelia wants to merge 10 commits into
mainfrom
lelia/prune-unrouted-sdk-calls

Conversation

@lelia

@lelia lelia commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Three SDK calls requested a path the API has no route for, so each one failed with a 404 on every request, whatever the token. The README scope table from #130 documents them as "no such route; the call fails". This PR removes them. It follows #131, which fixed the fourth call of this kind, settings.integration_events().

SDK call Path it requested What works
apitokens.update(token_id=...) PUT orgs/{org_slug}/api-tokens/{token_id} POST orgs/{org_slug}/api-tokens/update, with the token named in the body
dependencies.get(org_slug, ecosystem, package, version) GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version} POST dependencies/search
repositories.list() GET repos repos.get(org_slug)

Changes

  • apitokens.update() no longer takes token_id. It always posts to api-tokens/update. That endpoint reads the token to update from the request body, as exactly one of uuid, id, token or hash, so callers pass one of those as a keyword argument.
  • dependencies.get() no longer takes org_slug, ecosystem, package and version. Its signature is get(limit=50, offset=0), which is what the README already documents, and it always searches.
  • repositories is removed: the module, and the repositories attribute on the client. list() was its only method.
  • README: the scope table drops the three rows and the note about them. The apitokens.update example names the token with uuid instead of token_id, and uses scopes, the field the API accepts. The "Deprecated: repositories.get()" section is gone; that method never existed.
  • Bumps to 3.6.4, with a "Removed" changelog entry.

Compatibility

These are signature changes, so worth a careful look:

  • Every removed form already failed with a 404, so no working call to them breaks.
  • One working call changes. dependencies.get() bound positional arguments to the removed parameters and ignored them, so get(10, 0) ran with the default limit and offset. Positional arguments now set limit and offset. A call like dependencies.get("my-org") would now send that string as the limit.
  • Passing the removed keyword arguments to dependencies.get() raises TypeError. Passing token_id to apitokens.update() sends it in the body, and the API answers 400 because no valid identifier is present.
  • There are no callers of the removed forms in socket-python-cli or socket-basics.

Testing

Unit tests pass: 195 passed, 1 skipped. The updated tests assert the method, path and request body for apitokens.update() and dependencies.get(), and a new test checks that the removed package arguments raise TypeError without sending a request.

The mocked tests under tests/integration are not run in CI. I updated the ones that used the removed forms. The same 11 of them fail before and after this change, for unrelated reasons.

Public Changelog

Removed three SDK calls that could never succeed because the API has no route for them: apitokens.update(token_id=...), the four-argument form of dependencies.get(), and repositories.list().

Fixes: CE-513
Refs: CE-462

Add an "API token scopes" section to the README that maps every SDK
method to the endpoint it calls and the scopes that endpoint checks,
matching the per-endpoint scopes in the public API reference.

It also explains how a 401 or 403 surfaces: a missing scope raises
APIAccessDenied with status_code 403 and the server's "Insufficient
permissions" message, and 403s with more specific messages raise
APIInsufficientPermissions, APIOrganizationNotAllowed or
APIInsufficientQuota, all subclasses of APIFailure.

Methods whose endpoint the reference does not list are marked as such
rather than given a guessed scope.
The method requested orgs/{org}/settings/integrations/{id}, which has no
GET route, so it always failed. The events listing lives under /events
and checks integration:list.
GET .../integrations/{integration_id}/events answers with a bare JSON
array of events. The method was annotated -> dict and fell back to {},
and its test mocked a {"results": [...]} wrapper the API never sends.
The annotation and fallback are now a list, and the fixture has the
shape of a real event.
Checked against the API's route handlers:

- Three calls request a path with no route and always fail with a 404:
  apitokens.update(token_id=...), dependencies.get() with all four
  arguments, and repositories.list(). They were marked "not in the API
  reference", which read as working but undocumented.
- sbom.view() checks report:read.
- settings.integration_events() is listed with the /events path and
  integration:list.
- POST dependencies/search checks no scope at the route but filters
  results by dependencies:list repository access.
- The API sends neither "Insufficient permissions for API method" nor
  "Organization not allowed", so APIInsufficientPermissions and
  APIOrganizationNotAllowed are not raised today. A missing scope is
  APIAccessDenied.

Also marks the endpoints the API reference lists as deprecated, and
explains scope groups and tokens restricted to specific repositories.
Three calls could not succeed, because the API has no route for the
path they requested:

- apitokens.update(token_id=...) sent PUT orgs/{org}/api-tokens/{id}.
  The method now always posts to api-tokens/update, which reads the
  token from the request body.
- dependencies.get() with org_slug, ecosystem, package and version sent
  GET orgs/{org}/dependencies/... The method now only searches, with the
  get(limit, offset) signature the README documents. Positional
  arguments used to bind to the removed parameters and were ignored.
- repositories.list() sent GET repos. The module is removed;
  repos.get(org_slug) lists repositories.

The README scope table drops the three rows and their note, and its
apitokens.update example names the token with uuid instead of token_id.
@lelia

lelia commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor

cursor Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR Summary

Medium Risk
Breaking signature changes on apitokens.update(), dependencies.get(), and removal of repositories; one subtle behavior change where positional args to dependencies.get() now set pagination instead of being ignored.

Overview
Release 3.6.4 removes three SDK entry points that always hit nonexistent API routes (404) and aligns the survivors with the documented contract.

apitokens.update() no longer accepts token_id or uses PUT .../api-tokens/{id}; it always POSTs to api-tokens/update with the target token identified in the body via one of uuid, id, token, or hash.

dependencies.get() is narrowed to get(limit=50, offset=0) and always searches via POST dependencies/search; the per-package GET form is gone. Positional args now map to limit and offset (a behavior change for callers that passed org/package args positionally).

The repositories client and socket.repositories are deleted—listing repos should use repos.get(). Docs, changelog, and unit/integration tests are updated accordingly.

Reviewed by Cursor Bugbot for commit f978eb4. Configure here.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

…anded

The branch was stacked on both. Its diff against main is now only the
removal of the three unrouted calls, as 3.6.4.
@lelia
lelia marked this pull request as ready for review November 20, 2026 22:19
@lelia
lelia requested a review from a team as a code owner November 20, 2026 22:19
@lelia

lelia commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit f978eb4. Configure here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants