You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: src/routing/http-routing-v1.md
+46-51
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ description: >
4
4
Delegated routing is a mechanism for IPFS implementations to use for offloading
5
5
content routing, peer routing and naming to another process/server. This specification describes
6
6
an HTTP API for delegated routing of content, peers, and IPNS.
7
-
date: 2024-03-22
7
+
date: 2024-10-29
8
8
maturity: reliable
9
9
editors:
10
10
- name: Gus Eggert
@@ -21,14 +21,19 @@ editors:
21
21
url: https://hacdias.com/
22
22
github: hacdias
23
23
affiliation:
24
-
name: Protocol Labs
25
-
url: https://protocol.ai/
24
+
name: Shipyard
25
+
url: https://ipshipyard.com
26
26
- name: Marcin Rataj
27
27
github: lidel
28
28
url: https://lidel.org/
29
29
affiliation:
30
-
name: Protocol Labs
31
-
url: https://protocol.ai/
30
+
name: Shipyard
31
+
url: https://ipshipyard.com
32
+
- name: Daniel Norman
33
+
github: 2color
34
+
affiliation:
35
+
name: Shipyard
36
+
url: https://ipshipyard.com
32
37
xref:
33
38
- ipns-record
34
39
order: 0
@@ -67,29 +72,35 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac
67
72
68
73
#### Request Query Parameters
69
74
70
-
-`?filter-addrs`: Network Address Filtering
71
-
-`?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].
72
-
- The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`.
73
-
-`unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering.
74
-
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
75
-
- 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).
76
-
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
77
-
- If only negative filters are provided, addresses not passing any of the negative filters are included.
78
-
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
79
-
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
80
-
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
81
-
- Filtering is case-insensitive.
82
-
-`?filter-protocols`: IPFS Protocol Filtering
83
-
-`?filter-protocols=<comma-separated-list>` optional parameter to filter providers based on the `Protocol` field of the [Peer schema].
84
-
- The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`.
85
-
- 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](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151).
86
-
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
87
-
- 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.
88
-
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
89
-
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
90
-
- 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)
91
-
- Filtering is case-insensitive.
92
-
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
Optional `?filter-addrs` to apply Network Address Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/).
78
+
79
+
-`?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](#peer-schema).
80
+
- 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](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=tls,webrtc-direct,webtransport`.
81
+
-`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).
82
+
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
83
+
- 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).
84
+
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
85
+
- If only negative filters are provided, addresses not passing any of the negative filters are included.
86
+
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
87
+
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
88
+
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
Optional `?filter-protocols` to apply IPFS Protocol Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/).
94
+
95
+
- 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`.
96
+
- 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](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151).
97
+
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
98
+
- 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.
99
+
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
100
+
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
101
+
- 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)
102
+
- Filtering is case-insensitive.
103
+
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
93
104
94
105
#### Response Status Codes
95
106
@@ -141,29 +152,13 @@ represented as a CIDv1 encoded with `libp2p-key` codec.
141
152
142
153
#### Request Query Parameters
143
154
144
-
-`?filter-addrs`: Network Address Filtering
145
-
-`?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].
146
-
- The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`.
147
-
-`unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering.
148
-
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
149
-
- 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).
150
-
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
151
-
- If only negative filters are provided, addresses not passing any of the negative filters are included.
152
-
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
153
-
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
154
-
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
155
-
- Filtering is case-insensitive.
156
-
-`?filter-protocols`: IPFS Protocol Filtering
157
-
-`?filter-protocols=<comma-separated-list>` optional parameter to filter providers based on the `Protocol` field of the [Peer schema].
158
-
- The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`.
159
-
- 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](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151).
160
-
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
161
-
- 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.
162
-
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
163
-
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
164
-
- 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)
165
-
- Filtering is case-insensitive.
166
-
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
0 commit comments