diff --git a/src/ipips/ipip-0417.md b/src/ipips/ipip-0417.md new file mode 100644 index 000000000..d287375ad --- /dev/null +++ b/src/ipips/ipip-0417.md @@ -0,0 +1,60 @@ +--- +title: "IPIP-0417: Delegated Peer Routing HTTP API" +date: 2023-05-29 +ipip: proposal +editors: + - name: Henrique Dias + github: hacdias + url: https://hacdias.com/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ +relatedIssues: + - https://github.com/ipfs/specs/pull/410 + - https://github.com/ipfs/kubo/pull/9877 +order: 417 +tags: ['ipips'] +--- + +## Summary + +This IPIP specifies `/routing/v1/peers/{peer-id}` HTTP API to offload peer routing onto another server. + +## Motivation + +The motivation of this IPIP extends the one of :cite[ipip-0337] and :cite[ipip-0379], +which introduced delegated content routing and delegated naming, respectively. Now, +we expand upon those basis to introduce peer routing, reducing the barrier for interaction +across different systems. + +## Detailed design + +Add `/routing/v1/peers/{peer-id}` to the existing :cite[http-routing-v1] specification, +as well as the new Peer schema. + +## Design rationale + +In line with the remaining Routing V1 API, this IPIP introduces a new HTTP GET +endpoint that is used to retrieve peer records for a certain peer. + +### User benefit + +The user benefit brought by this PR is similar to the one in :cite[ipip-0379], +but instead of offloading the naming process, we offload the peer discovery and +routing. + +### Compatibility + +See the "Compatibility" section of :cite[ipip-0337]. + +### Security + +TODO + +### Alternatives + +TODO + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 480f930fc..655467184 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -102,6 +102,25 @@ Response limit: 100 providers Each object in the `Providers` list is a *read provider record*. +## Peers API + +### `GET /routing/v1/peers/{peer-id}` + +#### Path Parameters + +- `peer-id` is the [Peer ID](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md) to fetch peer records for, +represented as a CIDv1 encoded with `libp2p-key` codec. + +#### 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. + +#### Response Body + +A [`peer` schema record](#peer). + ## IPNS API ### `GET /routing/v1/ipns/{name}` @@ -199,6 +218,28 @@ Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, OPTIONS ``` +## Known Schemas + +This section contains a non-exhaustive list of known schemas that MAY be supported by clients and servers. + +### Peer + +The `peer` schema represents an arbitrary peer. + +```json +{ + "Schema": "peer", + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + "Protocols": ["transport-bitswap", ...] +} +``` + +- `ID`: the [Peer ID](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md). +- `Addrs`: a list of known [multiaddrs][multiaddr] for this peer. This list MAY be incomplete. +- `Protocols`: a list of protocols known to be supported by this peer. + - If empty, it means the server is missing protocol information, and the client should use `ID` and `Addrs` to connect to the peer and use the [libp2p identify protocol](https://github.com/libp2p/specs/tree/master/identify) to learn about supported ones. + ## Known Transfer Protocols This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers.