Skip to content

Commit 9c47a31

Browse files
committed
Address lint issues
Fix lint issues as reported by GitHub `super-liner`, including: - empty lines surrounding headers. - maximum line length. - unique headers - natural language. - tailing space.
1 parent 325ca1e commit 9c47a31

1 file changed

Lines changed: 33 additions & 23 deletions

File tree

routing/DELEGATED_CONTENT_ROUTING_HTTP.md

Lines changed: 33 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Delegated Content Routing HTTP API
44

55
**Author(s)**:
6+
67
- Gus Eggert
78

89
**Maintainer(s)**:
@@ -13,25 +14,28 @@
1314

1415
"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.
1516

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.
1820

1921
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.
2022

21-
## Common Data Types:
23+
## Common Data Types
2224

2325
- CIDs are always string-encoded using a [multibase](https://github.com/multiformats/multibase)-encoded [CIDv1](https://github.com/multiformats/cid#cidv1).
2426
- Multiaddrs are string-encoded according to the [human-readable multiaddr specification](https://github.com/multiformats/multiaddr#specification)
2527
- 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.
2729
- Timestamps are Unix millisecond epoch timestamps
2830

2931
Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields.
3032

3133
### Versioning
34+
3235
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.
3336

3437
### Provider Records
38+
3539
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.
3640

3741
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:
4852
}
4953
```
5054

51-
where:
55+
Where:
5256

5357
- `Protocol` is the multicodec name of the transfer protocol
5458
- `Schema` denotes the schema to use for encoding/decoding the record
@@ -58,26 +62,28 @@ where:
5862

5963
Specifications for some transfer protocols are provided in the "Transfer Protocols" section.
6064

61-
6265
## API
66+
6367
### `GET /routing/v1/providers/{CID}`
68+
6469
- Response codes
6570
- `200`: the response body contains 0 or more records
6671
- `404`: must be returned if no matching records are found
6772
- `422`: request does not conform to schema or semantic constraints
6873
- 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+
8187
- Default limit: 100 providers
8288
- Optional query parameters
8389
- `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:
9298

9399
- If there are more results, then a `NextPageToken` field should include an opaque string value, otherwise it should be undefined
94100
- 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
96102
- The client continues this process until `NextPageToken` is undefined or doesn't care to continue
97103
- A `pageLimit` query parameter specifies the maximum size of a single page
98104

99105
### Implementation Notes
100106

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.
102109

103110
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.
104111

@@ -118,21 +125,23 @@ request to the endpoints defined in this specification, and read the received
118125
values. This means HTTP server implementing this API must (1) support
119126
[CORS preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request)
120127
sent as HTTP OPTIONS, and (2) always respond with headers that remove CORS
121-
limits, allowing every website to query the API for results:
128+
limits, allowing every site to query the API for results:
122129

123130
```plaintext
124131
Access-Control-Allow-Origin: *
125132
Access-Control-Allow-Methods: GET, OPTIONS
126133
```
127134

128135
## Known Transfer Protocols
136+
129137
This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers.
130138

131139
### Bitswap
140+
132141
Multicodec name: `transport-bitswap`
133142
Schema: `bitswap`
134143

135-
#### Read Provider Records
144+
#### Bitswap Read Provider Records
136145

137146
```json
138147
{
@@ -150,10 +159,11 @@ Schema: `bitswap`
150159
The server should respect a passed `transport` query parameter by filtering against the `Addrs` list.
151160

152161
### Filecoin Graphsync
162+
153163
Multicodec name: `transport-graphsync-filecoinv1`
154164
Schema: `graphsync-filecoinv1`
155165

156-
#### Read Provider Records
166+
#### Filecoin Graphsync Read Provider Records
157167

158168
```json
159169
{

0 commit comments

Comments
 (0)