Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes a vendor-agnostic HTTP API for delegated content routing.
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.
Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields.
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.
A provider record contains information about a content provider, including the transfer protocol and any protocol-specific information useful for fetching the content from the provider.
The information required to write a record to a router ("write" provider records) may be different than the information contained when reading provider records ("read" provider records).
For example, indexers may require a signature in bitswap write records for authentication of the peer contained in the record, but the read records may not include this authentication information.
Both read and write provider records have a minimal required schema as follows:
{
"Protocol": "<transfer_protocol_name>",
"Schema": "<transfer_protocol_schema>",
...
}
Where:
Protocol is the multicodec name of the transfer protocol or an opaque string (for experimenting with novel protocols without a multicodec)Schema denotes the schema to use for encoding/decoding the record
Protocol to allow this HTTP API to evolve independently of the transfer protocolProtocol... denotes opaque JSON, which may contain information specific to the transfer protocolSpecifications for some transfer protocols are provided in the "Transfer Protocols" section.
GET /routing/v1/providers/{cid}cid is the CID to fetch provider records for.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.{
"Providers": [
{
"Protocol": "<protocol_name>",
"Schema": "<schema>",
...
}
]
}
Response limit: 100 providers
Each object in the Providers list is a read provider record.
GET /routing/v1/ipns/{name}name is the IPNS Name to resolve, encoded as CIDv1.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.Etag: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body.Cache-Control: max-age={TTL}: cache TTL returned with IPNS Record that has IpnsEntry.data[TTL] > 0. When present, SHOULD match the TTL value from the record. When record was not found (HTTP 404) or has no TTL (value is 0), implementation SHOULD default to max-age=60.The response body contains a IPNS Record serialized using the verifiable application/vnd.ipfs.ipns-record protobuf format.
PUT /routing/v1/ipns/{name}name is the IPNS Name to publish, encoded as CIDv1.The content body must be a application/vnd.ipfs.ipns-record serialized IPNS Record, with a valid signature matching the name path parameter.
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.This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update.
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-compatibile with clients and servers that do not support streaming:
Accept: application/x-ndjson header MUST default to
regular, non-streaming, JSON responses.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.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.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, OPTIONSThis section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers.
transport-bitswapbitswap{
"Protocol": "transport-bitswap",
"Schema": "bitswap",
"ID": "12D3K...",
"Addrs": ["/ip4/..."]
}
ID: the Peer ID to contactAddrs: a list of known multiaddrs for the peer
The server should respect a passed transport query parameter by filtering against the Addrs list.
transport-graphsync-filecoinv1graphsync-filecoinv1{
"Protocol": "transport-graphsync-filecoinv1",
"Schema": "graphsync-filecoinv1",
"ID": "12D3K...",
"Addrs": ["/ip4/..."],
"PieceCID": "<cid>",
"VerifiedDeal": true,
"FastRetrieval": true
}
ID: the Peer ID of the providerAddrs: a list of known multiaddrs for the providerPieceCID: the CID of the piece within which the data is storedVerifiedDeal: whether the deal corresponding to the data is verifiedFastRetrieval: whether the provider claims there is an unsealed copy of the data available for fast retrieval