Delegated Routing V1 HTTP API

status: reliable
Editors
Gus Eggert (Protocol Labs) GitHub
Masih H. Derkani (Protocol Labs) GitHub
Henrique Dias (Protocol Labs) GitHub
Marcin Rataj (Protocol Labs) GitHub
History
Commit History
Feedback
GitHub ipfs/specs (pull requests, new issue, open issues)

Delegated routing is a mechanism for IPFS implementations to use for offloading content routing, peer routing, and naming to another process/server. This specification describes a vendor-agnostic HTTP API for delegated content routing.

1. API Specification

The Routing HTTP API uses the application/json content type by default. For IPNS Names, the verifiable application/vnd.ipfs.ipns-record content type is used.

As such, human-readable encodings of types are preferred. This specification may be updated in the future with a compact application/cbor encoding, in which case compact encodings of the various types would be used.

2. Common Data Types

Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields.

3. Versioning

This API uses a standard version prefix in the path, such as /v1/.... If a backwards-incompatible change must be made, then the version number should be increased.

4. Content Routing API

4.1 GET /routing/v1/providers/{cid}

4.1.1 Path Parameters

  • cid is the CID to fetch provider records for.

4.1.2 Response Status Codes

  • 200 (OK): the response body contains 0 or more records.
  • 404 (Not Found): must be returned if no matching records are found.
  • 422 (Unprocessable Entity): request does not conform to schema or semantic constraints.

4.1.3 Response Headers

  • Content-Type: the content type of this response, which MUST be application/json or application/x-ndjson (see streaming).
  • Last-Modified: an HTTP-date timestamp (RFC9110, Section 5.6.7) of the resolution, allowing HTTP proxies and CDNs to support inexpensive update checks via If-Modified-Since
  • Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={max-ttl}, stale-if-error={max-ttl}: meaningful cache TTL returned with the response.
    • The max-age SHOULD be shorter for responses whose resolution ended in no results (e.g. 15 seconds), and longer for responses that have results (e.g. 5 minutes).
    • Implementations SHOULD include max-ttl, set to the maximum cache window of the underlying routing system. For example, if Amino DHT results are returned, stale-while-revalidate SHOULD be set to 172800 (48h, which at the time of writing this specification, is the provider record expiration window).
  • Vary: Accept: allows intermediate caches to play nicely with the different possible content types.

4.1.4 Response Body

{
  "Providers": [
    {
      "Schema": "<schema>",
      "ID": "bafz...",
      "Addrs": ["/ip4/..."],
      ...
    },
    ...
  ]
}

The application/json responses SHOULD be limited to 100 providers.

The client SHOULD be able to make a request with Accept: application/x-ndjson and get a stream with more results.

Each object in the Providers list is a record conforming to a schema, usually the Peer Schema.

5. Peer Routing API

5.1 GET /routing/v1/peers/{peer-id}

5.1.1 Path Parameters

  • peer-id is the Peer ID to fetch peer records for, represented as a CIDv1 encoded with libp2p-key codec.

5.1.2 Response Status Codes

  • 200 (OK): the response body contains the peer record.
  • 404 (Not Found): must be returned if no matching records are found.
  • 422 (Unprocessable Entity): request does not conform to schema or semantic constraints.

5.1.3 Response Headers

  • Content-Type: the content type of this response, which MUST be application/json or application/x-ndjson (see streaming).
  • Last-Modified: an HTTP-date timestamp (RFC9110, Section 5.6.7) of the resolution, allowing HTTP proxies and CDNs to support inexpensive update checks via If-Modified-Since
  • Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={max-ttl}, stale-if-error={max-ttl}: meaningful cache TTL returned with the response.
    • When present, ttl SHOULD be shorter for responses whose resolution ended in no results (e.g. 15 seconds), and longer for responses that have results (e.g. 5 minutes).
    • Implementations SHOULD include max-ttl, set to the maximum cache window of the underlying routing system. For example, if Amino DHT results are returned, stale-while-revalidate SHOULD be set to 172800 (48h, which at the time of writing this specification, is the provider record expiration window).
  • Vary: Accept: allows intermediate caches to play nicely with the different possible content types.

5.1.4 Response Body

{
  "Peers": [
    {
      "Schema": "<schema>",
      "Protocols": ["<protocol-a>", "<protocol-b>", ...],
      "ID": "bafz...",
      "Addrs": ["/ip4/..."],
      ...
    },
    ...
  ]
}

The application/json responses SHOULD be limited to 100 peers.

The client SHOULD be able to make a request with Accept: application/x-ndjson and get a stream with more results.

Each object in the Peers list is a record conforming to the Peer Schema.

6. IPNS API

6.1 GET /routing/v1/ipns/{name}

6.1.1 Path Parameters

  • name is the IPNS Name to resolve, encoded as CIDv1.

6.1.2 Response Status Codes

  • 200 (OK): the response body contains the IPNS Record for the given IPNS Name.
  • 404 (Not Found): must be returned if no matching records are found.
  • 406 (Not Acceptable): requested content type is missing or not supported. Error message returned in body should inform the user to retry with Accept: application/vnd.ipfs.ipns-record.

6.1.3 Response Headers

  • Etag: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body.
  • Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={sig-ttl}, stale-if-error={sig-ttl}: meaningful cache TTL returned with IPNS Record
    • The max-age value in seconds SHOULD match duration from IpnsEntry.data[TTL], if present and bigger than 0. Otherwise, implementation SHOULD default to max-age=60.
    • Implementations SHOULD include sig-ttl, set to the remaining number of seconds the returned IPNS Record is valid.
  • Expires:: an HTTP-date timestamp (RFC9110, Section 5.6.7) when the validity of IPNS Record expires (if ValidityType=0, when signature expires)
  • Last-Modified: an HTTP-date timestamp of when cacheable resolution occured: allows HTTP proxies and CDNs to support inexpensive update checks via If-Modified-Since
  • Vary: Accept: allows intermediate caches to play nicely with the different possible content types.

6.1.4 Response Body

The response body contains a IPNS Record serialized using the verifiable application/vnd.ipfs.ipns-record protobuf format.

6.2 PUT /routing/v1/ipns/{name}

6.2.1 Path Parameters

  • name is the IPNS Name to publish, encoded as CIDv1.

6.2.2 Request Body

The content body must be a application/vnd.ipfs.ipns-record serialized IPNS Record, with a valid signature matching the name path parameter.

6.2.3 Response Status Codes

  • 200 (OK): the provided IPNS Record was published.
  • 400 (Bad Request): the provided IPNS Record or IPNS Name are not valid.
  • 406 (Not Acceptable): submitted content type is not supported. Error message returned in body should inform the user to retry with Content-Type: application/vnd.ipfs.ipns-record.

7. Pagination

This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update.

8. Streaming

JSON-based endpoints support streaming requests made with Accept: application/x-ndjson HTTP Header.

Steaming responses are formatted as Newline Delimited JSON (ndjson), with one result per line:

{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}
...

Streaming is opt-in and backwards-compatible with clients and servers that do not support streaming:

9. Error Codes

10. CORS and Web Browsers

Browser interoperability requires implementations to support CORS.

JavaScript client running on a third-party Origin must be able to send HTTP request to the endpoints defined in this specification, and read the received values. This means HTTP server implementing this API must (1) support CORS preflight requests sent as HTTP OPTIONS, and (2) always respond with headers that remove CORS limits, allowing every site to query the API for results:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS

11. Known Schemas

This section contains a non-exhaustive list of known schemas that MAY be supported by clients and servers.

11.1 Peer Schema

The peer schema represents an arbitrary peer.

{
  "Schema": "peer",
  "ID": "bafz...",
  "Addrs": ["/ip4/..."],
  "Protocols": ["transport-bitswap", ...]
  ...
}

To allow for protocol-specific fields and future-proofing, the parser MUST allow for unknown fields, and the clients MUST ignore unknown ones.

Below is an example on how one could include protocol-a and protocol-b protocols that includes an additional fields protocol-a and protocol-b.

If the client knows the protocol, they are free to use the extra binary (base64) or JSON information contained in the additional field. If that is not the case, the field MUST be ignored.

{
  "Schema": "peer",
  "ID": "bafz...",
  "Addrs": ["/ip4/..."],
  "Protocols": ["transport-bitswap", "protocol-a", "protocol-b", ...],
  "protocol-a": "[base64-blob]",
  "protocol-b": { "foo": "bar" }
}

11.2 Legacy Schemas

Legacy schemas include ID and optional Addrs list just like the peer schema does.

These schemas are deprecated and SHOULD be replaced with peer over time, but MAY be returned by some legacy endpoints. In such case, a client MAY parse them the same way as the peer schema.

11.2.1 Bitswap Schema

A legacy schema used by some routers to indicate a peer supports retrieval over the /ipfs/bitswap[/*] libp2p protocol.

{
  "Protocol": "transport-bitswap",
  "Schema": "bitswap",
  "ID": "bafz...",
  "Addrs": ["/ip4/..."]
}

11.2.2 Graphsync Schema

A legacy schema used by some routers to indicate a peer supports retrieval over the graphsync libp2p protocol.

{
  "Protocol": "transport-graphsync-filecoinv1",
  "Schema": "graphsync-filecoinv1",
  "ID": "bafz...",
  "Addrs": ["/ip4/..."],
  "PieceCID": "<cid>",
  "VerifiedDeal": true,
  "FastRetrieval": true
}

A. References

[rfc2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119