skip to content
[readonly]

The registry API

JSON over HTTPS at https://sexc.dev/v1/. It is what sexc install and sexc publish use, and anything else may use it too.

  • Auth. Authorization: Bearer sexc_... with a token. Only POST /v1/tokens takes a password, as Basic auth.
  • Names go in paths as they are: /v1/packages/@ajax/strbuf.
  • Errors are {"ok": false, "error": "...", "code": "..."}: a sentence that says what to do, and a stable slug. 400 bad input, 401 no or bad credentials, 403 not allowed, 404, 409 conflict, 413 too large, 429 slow down.
  • Successes have "ok": true.

ENDPOINTS

POST /v1/accounts
Sign up. Body {"username", "email", "password"}. 201 {"ok": true, "username"}; 409 username_taken or email_taken. Five an hour per address.
POST /v1/tokens
Make an API token. Authorization: Basic with username:password (or email). Body {"name": "laptop", "scope": "publish"}, both optional; scope is publish or read. 201 with token (shown once), id, name, scope, username. Ten failed logins an hour per address, then 429.
GET /v1/tokens
Your tokens, never their secrets: id, name, scope, created, last_used.
DELETE /v1/tokens/:id
Revoke one.
GET /v1/whoami
username, email, scope, and token_id (the token you sent).
GET /v1/packages/:name
The packument: name, description, keywords, license, homepage, repository, owners, latest, created, updated, readme, and versions, keyed by version in semver order, each with manifest, dependencies, integrity, size, tarball, published, publisher, yanked, yank_reason.
GET /v1/packages/:name/:version
One version object, plus name.
PUT /v1/packages/:name
Publish. A publish token, and body {"version", "integrity": "sha256:<hex>", "tarball": "<base64 .tgz>"} up to 16 MiB. 201; 409 version_exists; 403 wrong_scope or not_owner; 400 with the reason for anything wrong in the tarball or its manifest.
POST /v1/packages/:name/:version/yank
Body {"reason"}, optional. The version stays downloadable for lockfiles; resolution skips it.
POST /v1/packages/:name/:version/unyank
Undo a yank.
GET /v1/tarballs/:name/:version.tgz
The tarball, application/gzip, cached forever.
GET /v1/search?q=&limit=20&offset=0
total and results: name, version, description, keywords, updated. Searches names, descriptions, keywords and READMEs; no q lists the most recently updated.
GET /v1/users/:username
username, created and their packages.

PUBLISHING BY HAND

$ sexc pack                       # writes ajax-strbuf-1.2.0.tgz
$ curl -X PUT https://sexc.dev/v1/packages/@ajax/strbuf \
    -H "Authorization: Bearer $SEXC_TOKEN" -H 'Content-Type: application/json' \
    -d "{\"version\":\"1.2.0\",\"integrity\":\"sha256:$(sha256sum < ajax-strbuf-1.2.0.tgz | cut -c1-64)\",\"tarball\":\"$(base64 -w0 ajax-strbuf-1.2.0.tgz)\"}"

sexc publish does all of that, and rewrites workspace:* dependencies to real ranges first.

RULES

  • @scope/ is your username: only you publish under it. Unscoped names are first come, first served.
  • Versions are immutable. Yank a bad one; publish a fixed one.
  • A tarball holds package/sexc.json and the rest under package/: regular files only, no links, no .., at most 10 MiB compressed, 50 MiB unpacked and 10 000 files.
  • Every dependency must already be published, with a version matching its range.
  • Packages marked "private": true are refused.

THE WEBSITE

The pages under packages/ have .json twins with the same data: /packages.json?q=, /packages/@ajax/strbuf.json, /packages/@ajax/strbuf/v/1.2.0.json, /packages/@ajax/strbuf/v/1.2.0/files.json, /~ajax.json.