docs: start IPIP 0417

Co-authored-by: Marcin Rataj <lidel@lidel.org>
ipfs · Jul 31, 2023 · 4ee487a · 4ee487a
1 parent 7545f1e
commit 4ee487a
Show file tree

Hide file tree

Showing 2 changed files with 101 additions and 0 deletions.
diff --git a/src/ipips/ipip-0417.md 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
@@ -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.