Thread by @isntitvacant

would anyone be interested in a brief explanation of the flow of API requests for a npm package install, or is this already general knowledge?

okay, I'll write this up in a larger form elsewhere, later, but: no time like the present and no... medium... like... the twitter feed, I suppose

here are the basic types in play:

a package has one metadata document, a JSON "packument"
a packument lists all of the versions of the package and the times they were published
a version has a tarball

there are two API endpoints:

- /${pkg urlencoded} for packuments
- /${pkg}/-/${name}-${version}.tgz for tarballs

e.g.:
- /lodash and /lodash/-/lodash-4.17.11.tgz, or
- /%40slack%2fclient and /﹫slack/client/-/client-4.8.0.tgz

(forgive the @-homoglyph there)

packuments contain {"versions": {[version]: Version}, "time": {[version]: Date}, "dist-tags": {"latest": [version], ...}}

if there's a version in "time" but not in "versions", it's been unpublished

"dist-tags" contains tag names, and is required to have "latest"

I'm handwaving the CLI magic that goes on (and it is really cool, check out zkat/pacote + cacache), BUT, generally the flow is:

GET /<pkg>
<figure out which version you wanted>
GET /<pkg>/-/<pkg>-<version>.tgz

(repeated for all <pkg>'s in the tree you want to install)

other stuff:

- send an accept header of "application/vnd.npm.install-v1+json" to get a shorter (or "corgi") packument (your CLI does this for you)
- to authorize a request, send "authorization: Bearer <your token>" (you can use basic auth too but please, please don't.)

- corgi packuments also advertise whether or not package-versions contain a shrinkwrap file, which saves CLIs a trip through untar
- each package-version contains a dist stanza with an SRI hash, unpacked size, file count, and npm signature

for public packages: you can get an ndjson list of the files+sizes inside the tarball! see:

GET /lodash/-/lodash-4.17.11.index (replacing "tgz" with "index")

(💞 to @soldair for this)