From d9819e10c0af58a42f1e3df4361a94d100b42b53 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Mon, 29 May 2023 12:12:57 +0200 Subject: [PATCH] docs: merge ipns routing with routing v1 spec --- src/ipips/ipip-0379.md | 2 +- src/routing/http-ipns-routing.md | 179 ------------------------------- src/routing/http-routing-v1.md | 110 ++++++++++++++----- 3 files changed, 84 insertions(+), 207 deletions(-) delete mode 100644 src/routing/http-ipns-routing.md diff --git a/src/ipips/ipip-0379.md b/src/ipips/ipip-0379.md index 0b8c82c59..4702d838d 100644 --- a/src/ipips/ipip-0379.md +++ b/src/ipips/ipip-0379.md @@ -30,7 +30,7 @@ The performance of naming system over the IPFS DHT can suffer from long delays d ## HTTP API Specification -See :cite[http-ipns-routing] specification. +See :cite[http-routing-v1] specification. ## Design rationale diff --git a/src/routing/http-ipns-routing.md b/src/routing/http-ipns-routing.md deleted file mode 100644 index 5f2d048c9..000000000 --- a/src/routing/http-ipns-routing.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Delegated IPNS HTTP API -description: > - Delegated IPNS is a mechanism for IPFS implementations to offload naming system to another process - or server. This includes naming resolution as well as publication of new naming records. This - document describes an HTTP API through which such functionality is facilitated. -date: 2023-03-22 -maturity: wip -editors: - - name: Masih H. Derkani - github: masih -order: 0 -tags: ['routing'] ---- - -Delegated IPNS is a mechanism for IPFS implementations to offload naming system to another process -or server. This includes naming resolution as well as publication of new naming records. This -document describes an HTTP API through which such functionality is facilitated. - -## API Specification - -The Delegated IPNS HTTP API uses the `application/json` content type by default. - -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. - -## Common Data Types - -### IPNS Record - -The following snippet outlines the JSON schema of IPNS records: - -```json -{ - "Signature": "", - "Payload": { - "Value": "", - "Sequence": 0, - "Validity": { - "EOL": { - "Timestamp": 0, - "AdvisoryTTL": 0 - } - }, - "PublicKey": "", - "ExtendedData": {} - } -} -``` - -Where: - -- `Signature` is the multibase-encoded signature of the sha256 hash of the `Payload` field, signed - using the private key that corresponds to the `PublicKey` in the `Payload` if present. And - Otherwise, the private key associcated to the IPNS record key. Signing details for specific key - types should - follow [libp2p/peerid specs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#key-types), - unless stated otherwise. -- `Payload` is the content of the IPNS record as specified - by :cite[ipns-record] specification: -- `Value` is the string representation of the IPNS path, - e.g. `ipns/{ipns-key}`, `/ipns/example.com`, `/ipfs/baf...`, etc. -- `Sequence` represents the current version of the record starting from `0`. -- `Validity` captures the mechanism by which the record is validated. Each validity type reserves a - field key under this object. - - `EOL` donates that the validity type is EOL, containing: - - `Timestamp` represents the time in the future at which the record expires with nanoseconds - precision represented as an ASCII string that follows notation - from :cite[rfc3339]. - - `AdvisoryTTL` represents an optional field that hints at how long the record should be - cached. -- `PublicKey` represents the optional public key used to sign the record. This field is only - required if it cannot be extracted from the IPNS name, e.g. in the case of legacy RSA keys. - The idea here is that IPNS Record should always have all information neccessary - for signature verification in offline mode, without additional lookups to retrieve the public key. -- `ExtendedData` represents the extensible data as arbitrary JSON object. - -## Versioning - -The path predix `/v1` donates the version number of the HTTP API. Backwards-incompatible change must -increment the version number. - -## API - -### `GET /routing/v1/ipns/{ipns-name}` - -**Path Parameters** - -- `ipns-name` the IPNS name to resolve. - -**Response Status Codes** - -- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the - IPNS name. -- `404` (Not Found): indicates that no matching records are found. -- `400` (Bad Request): indicates that the given IPNS name is not valid. -- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may - retry after the time specified - at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response - header has elapsed. -- `501` (Not Implemented): indicates that the server does not support resolution of IPNS records - -**Response Body** - -The response body contains the [IPNS record](#ipns-record). - -```json -{ - "Signature": "", - "Payload": { - "Value": "", - "Sequence": 0, - "Validity": { - "EOL": { - "Timestamp": 0, - "AdvisoryTTL": 0 - } - }, - "PublicKey": "", - "ExtendedData": {} - } -} -``` - -### `PUT /routing/v1/ipns/{ipns-name}` - -**Path Parameters** - -- `ipns-name` the IPNS name to publish. The name must match `Value` in request body. - -**Request Body** - -```json -{ - "Signature": "", - "Payload": { - "Value": "", - "Sequence": 0, - "Validity": { - "EOL": { - "Timestamp": 0, - "AdvisoryTTL": 0 - } - }, - "PublicKey": "", - "ExtendedData": {} - } -} -``` - -**Response Status Codes** - -- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the - IPNS name. -- `404` (Not Found): indicates that no matching records are found. -- `400` (Bad Request): indicates that the given IPNS record is not valid. -- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may - retry after the time specified - at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response - header has elapsed. -- `501` (Not Implemented): indicates that the server does not support publication of IPNS records - -## CORS and Web Browsers - -Browser interoperability requires implementations to support -[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). - -JavaScript client running on a third-party Origin must be able to send HTTP request to the endpoints -defined in this specification, and read the received values. This means HTTP server implementing -this API must: - -1. support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) sent as HTTP OPTIONS, and -2. always respond with headers that remove CORS limits, allowing every site to query the API for results: - -```plaintext -Access-Control-Allow-Origin: * -Access-Control-Allow-Methods: GET, PUT, OPTIONS -``` diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index c19572183..6830316a8 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -1,25 +1,29 @@ --- title: Routing V1 HTTP API description: > - Delegated content routing is a mechanism for IPFS implementations to use for - offloading content routing to another process. This specification describes + Delegated routing is a mechanism for IPFS implementations to use for offloading + content routing and naming to another process/server. This specification describes an HTTP API for delegated content routing. date: 2023-03-22 maturity: reliable editors: - name: Gus Eggert - github: guseggert + github: guseggert + - name: Masih H. Derkani + github: masih +xref: + - ipns-record order: 0 tags: ['routing'] --- -"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. +Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes an HTTP API for delegated content routing. ## API Specification -The Delegated Content Routing Routing HTTP API uses the `application/json` content type by default. +The Routing HTTP API uses the `application/json` content type by default. For :ref[IPNS Names], the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record content type is used. -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. +As such, human-readable encodings of types are preferred. This specification may be updated in the future with a compact `application/cbor` encoding, in which case compact encodings of the various types would be used. ## Common Data Types @@ -27,7 +31,7 @@ As such, human-readable encodings of types are preferred. This spec may be updat - Multiaddrs are string-encoded according to the [human-readable multiaddr specification](https://github.com/multiformats/multiaddr#specification) - Peer IDs are string-encoded according [PeerID string representation specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation) - Multibase bytes are string-encoded according to [the Multibase spec](https://github.com/multiformats/multibase), and *should* use base64. -- Timestamps are Unix millisecond epoch timestamps +- Timestamps are Unix millisecond epoch timestamps. Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields. @@ -63,11 +67,19 @@ Where: Specifications for some transfer protocols are provided in the "Transfer Protocols" section. +### IPNS Records + +:ref[IPNS Records] are serialized using the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) format. For more details, read the specification :cite[ipns-record]. + ## API -### `GET /routing/v1/providers/{CID}` +### `GET /routing/v1/providers/{cid}` + +#### Path Parameters -#### Response codes +- `cid` is the [CID](https://github.com/multiformats/cid) to fetch provider records for. + +#### Response Status Codes - `200` (OK): the response body contains 0 or more records - `404` (Not Found): must be returned if no matching records are found @@ -77,13 +89,13 @@ Specifications for some transfer protocols are provided in the "Transfer Protoco ```json { - "Providers": [ - { - "Protocol": "", - "Schema": "", - ... - } - ] + "Providers": [ + { + "Protocol": "", + "Schema": "", + ... + } + ] } ``` @@ -91,6 +103,50 @@ Response limit: 100 providers Each object in the `Providers` list is a *read provider record*. +### `GET /routing/v1/ipns/{name}` + +#### Path Parameters + +- `name` is the :ref[IPNS Name] to resolve. + +#### Response Status Codes + +- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the + IPNS name. +- `404` (Not Found): indicates that no matching records are found. +- `400` (Bad Request): indicates that the given IPNS name is not valid. +- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may + retry after the time specified + at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response + header has elapsed. +- `501` (Not Implemented): indicates that the server does not support resolution of IPNS records + +#### Response Body + +The response body contains a [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) serialized :ref[IPNS Record]. + +### `PUT /routing/v1/ipns/{name}` + +#### Path Parameters + +- `name` is the :ref[IPNS Name] to publish. + +#### Request Body + +The content body must be a [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) serialized :ref[IPNS Record], which matches the `name` path parameter. + +#### Response Status Codes + +- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the + IPNS name. +- `404` (Not Found): indicates that no matching records are found. +- `400` (Bad Request): indicates that the given IPNS record is not valid. +- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may + retry after the time specified + at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response + header has elapsed. +- `501` (Not Implemented): indicates that the server does not support publication of IPNS records + ## Pagination This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update. @@ -136,10 +192,10 @@ Specification: [ipfs/specs/BITSWAP.md](https://github.com/ipfs/specs/blob/main/B ```json { - "Protocol": "transport-bitswap", - "Schema": "bitswap", - "ID": "12D3K...", - "Addrs": ["/ip4/..."] + "Protocol": "transport-bitswap", + "Schema": "bitswap", + "ID": "12D3K...", + "Addrs": ["/ip4/..."] } ``` @@ -159,13 +215,13 @@ Specification: [ipfs/go-graphsync/blob/main/docs/architecture.md](https://github ```json { - "Protocol": "transport-graphsync-filecoinv1", - "Schema": "graphsync-filecoinv1", - "ID": "12D3K...", - "Addrs": ["/ip4/..."], - "PieceCID": "", - "VerifiedDeal": true, - "FastRetrieval": true + "Protocol": "transport-graphsync-filecoinv1", + "Schema": "graphsync-filecoinv1", + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + "PieceCID": "", + "VerifiedDeal": true, + "FastRetrieval": true } ```