The registry API

A Hive registry is, first of all, files: for each package an index, Author/Name/index.json, and the package files beside it. larva hive reads them from a folder or over HTTPS. A registry on the web adds one request to publish. The public registry's root is https://www.antril.org/hive-api/.

A registry made of files

registry/
  Ana/
    Greetings/
      index.json
      1.0/Greetings-1.0.hive
      1.1/Greetings-1.1.hive
      2.0/Greetings-2.0.hive

larva hive publish to a folder writes exactly this (see Publishing packages). Any static web server that serves the folder over HTTPS is a registry too: larva hive only needs GET for installing. To publish to such a registry, publish to the folder, then upload it.

index.json

{
  "package": "Ana/Greetings",
  "keys": {
    "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt2nz5PDcKGyCEddkuAPfBauYEJVK4G3bfrFHnPyxn3r4UkfuUNsWCkhPMgBcQ3LBxGvu5O297PxsXhRrYvQ1UQ=="
  },
  "versions": [
    {
      "version": "1.0",
      "file": "1.0/Greetings-1.0.hive",
      "sha256": "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b",
      "key": "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d",
      "dependencies": [],
      "yanked": false
    }
  ]
}

The index is not signed: each package file is. What the index can change is checked when installing: the file must match sha256, its manifest must name the same package and version, its signature must be the key the index gives, and that key must be one the user trusts for the package (see What installing checks).

The HTTP API

Root: /hive-api/. Names in addresses are matched regardless of case.

Read an index

GET /hive-api/Ana/Greetings/index.json

200 OK
Content-Type: application/json
Cache-Control: no-cache

{ "package": "Ana/Greetings", "keys": { ... }, "versions": [ ... ] }

An unknown package answers 404 with the text no package Ana/Nothing. larva hive then tries the next registry.

Download a package file

GET /hive-api/Ana/Greetings/1.0/Greetings-1.0.hive

200 OK
Content-Type: application/octet-stream
Cache-Control: public, max-age=31536000, immutable
ETag: "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b"

The address is the index's file under the package's folder. A published file never changes, so it may be cached for good; its entity tag is its SHA-256. A version that is not written canonically, or a file that is not the version's, answers 404.

Publish a version

larva hive publish sends:

PUT /hive-api/Ana/Greetings/1.0
Authorization: Bearer hive_...
Hive-Sha256: 2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b
Hive-Public-Key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
Content-Length: 2976

<the .hive file>

On success:

201 Created
Content-Type: application/json

{
  "package": "Ana/Greetings",
  "version": "1.0",
  "file": "1.0/Greetings-1.0.hive",
  "sha256": "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b",
  "key": "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d"
}

Who may publish

The token must be valid: known, not revoked, not expired. The author (the first part of the name) must exist and be owned by the token's user. You get your own author when you sign up and can claim others on your account page: see Accounts, tokens and authors. A package's first publish creates it under that author.

The registry applies the same signing rules as larva hive does for a folder:

• a version is published once, and never replaced;
• a package's first version brings its key; later versions must be signed by a key the package already has;
• once a package is signed, an unsigned version is refused.

Errors

An error's body is plain text, and the same message is the HTTP/1.1 reason phrase, so larva hive publish shows it:

larva hive: https://www.antril.org/hive-api/Ana/Greetings/1.0: 403 you cannot publish as `Ana`

Messages as the registry writes them:

Running your own

Any folder or static HTTPS server works as a read-only registry, as above. The www.antril.org site, with accounts and publishing, can also run on your machine for testing; point larva at it with plain http, which is accepted only for localhost:

$ larva config hive.provider http://localhost:5080/hive-api
hive.provider: http://localhost:5080/hive-api

or, for one project, provider: http://localhost:5080/hive-api in its HIVE chunk.