Registries

Where indices can be thought of as the “read-only” part of a package repository, providing information about packages and nothing more, a registry is a package server which serves the actual package files and allows users to upload and yank packages from them.

All registries are tied to indices - a registry must have a corresponding package index (though the opposite isn’t necessarily true). Package registries can be specified as URLs in the configuration of an index with the following syntax:

API v1 Endpoints

It’s assumed that all package registries have some sort of auth system centered around a user token which allows the registry to authenticate and authorize different users. elba users can log in to a registry using the elba login <token> command, where token is the auth token provided to them by the registry.

In order to function with elba, package registries must support two basic operations:

  • Package publishing: package registries should be able to have packages uploaded to them at the PUT endpoint /api/v1/publish. The body of this request will be the package in archived (tar.gz) form, and the auth token will be provided as a query parameter token.
  • Package yanking: in order to prevent a left-pad-esque scenario, the public interface of a package registry prohibits package deletion; instead, packages can be yanked, which means that future packages will be unable to depend on said package or package version. A package group/name|version can be yanked at the PATCH endpoint /api/v1/group/name/version/yank. This endpoint should accept a boolean query parameter yanked (usually set to true) and a query parameter token.

Currently, these are the two endpoints which elba needs to function. However, the full list of endpoints is much longer than this, and can be found in the source code of the reference elba registry.