Delegated Routing V1 HTTP API (original) (raw)

29 October 2024

History

Feedback

GitHub ipfs/specs (inspect source, open issue)

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
2. Common Data Types
3. Versioning
4. Content Routing API
1. 4.1 GET /routing/v1/providers/{cid}
5. Peer Routing API
1. 5.1 GET /routing/v1/peers/{peer-id}
6. IPNS API
1. 6.1 GET /routing/v1/ipns/{name}
2. 6.2 PUT /routing/v1/ipns/{name}
7. Pagination
8. Streaming
9. Error Codes
10. CORS and Web Browsers
11. Known Schemas
11.1 Peer Schema
11.2 Legacy Schemas
1. 11.2.1 Bitswap Schema
2. 11.2.2 Graphsync Schema
A. References
B. Acknowledgments

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

CIDs are always string-encoded using a multibase-encoded CIDv1.
Multiaddrs are string-encoded according to the human-readable multiaddr specification.
Peer IDs are string-encoded according PeerID string representation specification: either a Multihash in Base58btc, or a CIDv1 with libp2p-key (0x72) codec in Base36 or Base32.
Multibase bytes are string-encoded according to the Multibase spec, and SHOULD use base64.
Timestamps are Unix millisecond epoch timestamps.

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 (preferably normalized to a CIDv1 in Base32, to maximize HTTP cache hits).

4.1.2 Request Query Parameters

4.1.2.1 `filter-addrs` (providers request query parameter)

Optional ?filter-addrs to apply Network Address Filtering from IPIP-484.

?filter-addrs=<comma-separated-list> optional parameter that indicates which network transports to return by filtering the multiaddrs in the Addrs field of the Peer schema.
The value of the filter-addrs parameter is a comma-separated (, or %2C) list of network transport protocol name strings as defined in the multiaddr protocol registry, e.g. ?filter-addrs=tls,webrtc-direct,webtransport.
unknown can be be passed to include providers whose multiaddrs are unknown, e.g. ?filter-addrs=unknown. This allows for not removing providers whose multiaddrs are unknown at the time of filtering (e.g. keeping DHT results that require additional peer lookup).
Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
Negative filtering is done by prefixing the protocol name with !, e.g. to skip IPv6 and QUIC addrs: ?filter-addrs=!ip6,!quic-v1. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND).
If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
If only negative filters are provided, addresses not passing any of the negative filters are included.
If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
Filtering is case-insensitive.

4.1.2.2 `filter-protocols` (providers request query parameter)

Optional ?filter-protocols to apply IPFS Protocol Filtering from IPIP-484.

The filter-protocols parameter is a comma-separated (, or %2C) list of transfer protocol names, e.g. ?filter-protocols=unknown,transport-bitswap,transport-ipfs-gateway-http.
Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the multicodec registry.
Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
A special unknown name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. ?filter-protocols=unknown. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information.
Providers are filtered by checking if the transfer protocol name appears in the Protocols array (logical OR).
If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from filter-addrs where only the multiaddrs that pass the filter are returned)
Filtering is case-insensitive.
If no parameter is passed, the default behavior is to not filter by transfer protocol.

4.1.3 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.5 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 either a Multihash in Base58btc, or a CIDv1 with libp2p-key (0x72) codec (in Base36 or Base32).

5.1.2 Request Query Parameters

5.1.2.1 `filter-addrs` (peers request query parameter)

Optional, same rules as filter-addrs providers request query parameter.

5.1.2.2 `filter-protocols` (peers request query parameter)

Optional, same rules as filter-protocols providers request query parameter.

5.1.3 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.5 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.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.

8. Streaming

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

Steaming responses are formatted asNewline 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:

Requests without the Accept: application/x-ndjson header MUST default to regular, non-streaming, JSON responses.
Legacy server MAY respond with non-streaming application/json response even if the client requested streaming. It is up to the client to inspect the Content-Type header before parsing the response.
The server MUST NOT respond with streaming response if the client did not explicitly request so.

9. Error Codes

400 (Bad Request): must be returned if an unknown path is requested.
429 (Too Many Requests): may be returned along with optional Retry-After header to indicate to the caller that it is issuing requests too quickly.
501 (Not Implemented): must be returned if a method/path is not supported.

10. CORS and Web Browsers

Browser interoperability requires implementations to supportCORS.

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) supportCORS preflight requestssent 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", ...]
  ...
}

ID: the Peer ID as Multihash in Base58btc or CIDv1 with libp2p-key codec.
Addrs: an optional list of known multiaddrs for this peer.
- If missing or empty, it means the router server is missing that information, and the client should use ID to lookup updated peer information.
Protocols: an optional list of protocols known to be supported by this peer.
- If missing or empty, it means the router server is missing that information, and the client should use ID and Addrs to lookup connect to the peer and use the libp2p identify protocol to learn about supported ones.

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-bprotocols 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 graphsynclibp2p 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

B. Acknowledgments

We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.

Editors

Gus Eggert (Protocol Labs)

Masih H. Derkani (Protocol Labs)

Henrique Dias (Shipyard)

Marcin Rataj (Shipyard)

Daniel Norman (Shipyard)