Discovery Document

Binary caches are typically referenced using a URL to a discovery document. The discovery document MUST be a JSON Hypertext Application Language (HAL) Document and SHOULD be served with a media type of application/hal+json.

The following sections describe the link relation types (as described in RFC 5988) used in the discovery document.

https://zb-build.dev/api/rel/narinfo

The https://zb-build.dev/api/rel/narinfo link relation type defines how to look up the metadata for a store object. Binary caches SHOULD provide this link in their discovery document. If provided, the discovery document MUST use an array of links for this link relation type. Each link MUST be a URI template.

The defined template parameters for URIs of this link relation type are:

base

The store object’s base file name.

digest

The digest portion of the store object’s base file name.

The linked resource SHOULD use the media type text/x-nix-narinfo. The linked resource MUST follow the .narinfo file format.

https://zb-build.dev/api/rel/nar

The https://zb-build.dev/api/rel/nar link relation type defines where to PUT NAR files when uploading to the binary cache. (For downloading, the URL in a store object’s .narinfo file is the canonical link.) Binary caches MUST provide this link if they support uploading. If provided, the discovery document MUST NOT use an array for this link relation type. The link MUST be a URI template.

The defined template parameters for URIs of this link relation type are:

base

The store object’s base file name.

digest

The digest portion of the store object’s base file name.

The linked resource SHOULD use the media type application/x-nix-nar.

https://zb-build.dev/api/rel/narlisting

The https://zb-build.dev/api/rel/narlisting link relation type provides NAR listings for store objects. Binary caches MAY provide this link in their discovery document to support efficient access of individual files in the NAR files. If provided, the discovery document MUST use an array of links for this link relation type. Each link MUST be a URI template. The URI template parameters are the same as for https://zb-build.dev/api/rel/narinfo.

https://zb-build.dev/api/rel/realization

The https://zb-build.dev/api/rel/realization link relation type provides mappings from derivation outputs to store objects. Binary caches SHOULD provide this link in their discovery document. If provided, the discovery document MUST use an array of links for this link relation type. Each link MUST be a URI template.

The defined template parameters for URIs of this link relation type are:

hashAlgorithm

One of md5, sha1, sha256, or sha512 depending on the hash.

hashDigest

The hash bits encoded with Nix Base-32.

hashDigestHex

The hash bits encoded as lowercase hexadecimal.

hashDigestBase64

The hash bits encoded as base64url with padding as described by RFC 4648 Section 5.

The linked resource SHOULD use the media type application/json. The resource MUST follow the realization format.