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: routing/DELEGATED_CONTENT_ROUTING_HTTP.md
+33-23Lines changed: 33 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@
3
3
 Delegated Content Routing HTTP API
4
4
5
5
**Author(s)**:
6
+
6
7
- Gus Eggert
7
8
8
9
**Maintainer(s)**:
@@ -13,25 +14,28 @@
13
14
14
15
"Delegated content routing" is a mechanism for IPFS implementations to use for offloading content routing to another process/server. This spec describes an HTTP API for delegated content routing.
15
16
16
-
# API Specification
17
-
The Delegated Content Routing Routing HTTP API uses the `application/json` content type by default.
17
+
## API Specification
18
+
19
+
The Delegated Content Routing Routing HTTP API uses the `application/json` content type by default.
18
20
19
21
As such, human-readable encodings of types are preferred. This spec may be updated in the future with a compact `application/cbor` encoding, in which case compact encodings of the various types would be used.
20
22
21
-
## Common Data Types:
23
+
## Common Data Types
22
24
23
25
- CIDs are always string-encoded using a [multibase](https://github.com/multiformats/multibase)-encoded [CIDv1](https://github.com/multiformats/cid#cidv1).
24
26
- Multiaddrs are string-encoded according to the [human-readable multiaddr specification](https://github.com/multiformats/multiaddr#specification)
25
27
- Peer IDs are string-encoded according [PeerID string representation specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation)
26
-
- Multibase bytes are string-encoded according to [the Multibase spec](https://github.com/multiformats/multibase), and *should* use Base64.
28
+
- Multibase bytes are string-encoded according to [the Multibase spec](https://github.com/multiformats/multibase), and *should* use base64.
27
29
- Timestamps are Unix millisecond epoch timestamps
28
30
29
31
Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields.
30
32
31
33
### Versioning
34
+
32
35
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.
33
36
34
37
### Provider Records
38
+
35
39
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.
36
40
37
41
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*).
@@ -48,7 +52,7 @@ Both read and write provider records have a minimal required schema as follows:
48
52
}
49
53
```
50
54
51
-
where:
55
+
Where:
52
56
53
57
-`Protocol` is the multicodec name of the transfer protocol
54
58
-`Schema` denotes the schema to use for encoding/decoding the record
@@ -58,26 +62,28 @@ where:
58
62
59
63
Specifications for some transfer protocols are provided in the "Transfer Protocols" section.
60
64
61
-
62
65
## API
66
+
63
67
### `GET /routing/v1/providers/{CID}`
68
+
64
69
- Response codes
65
70
-`200`: the response body contains 0 or more records
66
71
-`404`: must be returned if no matching records are found
67
72
-`422`: request does not conform to schema or semantic constraints
68
73
- Response Body
69
-
```json
70
-
{
71
-
"Providers": [
72
-
{
73
-
"Protocol": "<protocol_name>",
74
-
"Schema": "<schema>",
75
-
...
76
-
}
77
-
]
78
-
}
79
-
```
80
-
74
+
75
+
```json
76
+
{
77
+
"Providers": [
78
+
{
79
+
"Protocol": "<protocol_name>",
80
+
"Schema": "<schema>",
81
+
...
82
+
}
83
+
]
84
+
}
85
+
```
86
+
81
87
- Default limit: 100 providers
82
88
- Optional query parameters
83
89
-`transfer` only return providers who support the passed transfer protocols, expressed as a comma-separated list of transfer protocol names such as `transfer=bitswap,filecoin-graphsync-v1`
@@ -92,13 +98,14 @@ APIs that return collections of results should support pagination as follows:
92
98
93
99
- If there are more results, then a `NextPageToken` field should include an opaque string value, otherwise it should be undefined
94
100
- The value of `NextPageToken` can be specified as the value of a `pageToken` query parameter to fetch the next page
95
-
- Character set is restricted to the regex`[a-zA-Z0-9-_.~]+`, since this is intended to be used in URLs
101
+
- Character set is restricted to the regular expression`[a-zA-Z0-9-_.~]+`, since this is intended to be used in URLs
96
102
- The client continues this process until `NextPageToken` is undefined or doesn't care to continue
97
103
- A `pageLimit` query parameter specifies the maximum size of a single page
98
104
99
105
### Implementation Notes
100
106
101
-
Servers are required to return *at most*`pageLimit` results in a page. It is recommended for pages to be as dense as possible, but it is acceptable for them to return any number of items in the closed interval [0, pageLimit]. This is dependent on the capabilities of the backing database implementation. For example, a query specifying a `transfer` filter for a rare transfer protocol should not *require* the server to perform a very expensive database query for a single request. Instead, this is left to the server implementation to decide based on the constraints of the database.
107
+
Servers are required to return *at most*`pageLimit` results in a page. It is recommended for pages to be as dense as possible, but it is acceptable for them to return any number of items in the closed interval [0, pageLimit]. This is dependent on the capabilities of the backing database implementation.
108
+
For example, a query specifying a `transfer` filter for a rare transfer protocol should not *require* the server to perform a very expensive database query for a single request. Instead, this is left to the server implementation to decide based on the constraints of the database.
102
109
103
110
Implementations should encode into the token whatever information is necessary for fetching the next page. This could be a base32-encoded JSON object like `{"offset":3,"limit":10}`, an object ID of the last scanned item, etc.
104
111
@@ -118,21 +125,23 @@ request to the endpoints defined in this specification, and read the received
118
125
values. This means HTTP server implementing this API must (1) support
0 commit comments