From 1eaec807e9de29b0872a0adcc99fb8442674372c Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 14:06:03 +0200 Subject: [PATCH 1/7] Move depth to optional meta attributes As per feedback in https://github.com/ipfs/pinning-services-api-spec/pull/16 --- ipfs-pinning-service.yaml | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index 6752831..b1c188f 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -45,6 +45,19 @@ response. The old pin object is deleted automatically. Pin object can be removed via `DELETE /pins/{cid-of-pin-object}` +# Custom metadata + +Pinning Services are encouraged to add support for additional features by +leveraging optional `meta` attributes: + +- `PinStatus.meta[progress]` – % progress of ongoing pinning operation +- `Pin.meta[replication]` – could define how many copies service should keep +- `Pin.meta[depth]` – could define how deep the DAG should be pinned + +Those can be vendor-specific, but we encourrage community to leverage `meta` to +come up with conventions that could become part of mandatory revisions of this +API. + # Authorization An opaque auth token is required to be sent with each request. @@ -228,12 +241,6 @@ components: cid: description: CID to be pinned type: string - depth: - description: Defines how deep the DAG should be pinned (-1 recursive, 0 direct) - type: integer - format: int32 - default: -1 - minimum: -1 meta: $ref: '#/components/schemas/Meta' From 18f2c89a7356b30650756f5259007dc880548a1d Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 14:55:21 +0200 Subject: [PATCH 2/7] Add providers/receivers to meta examples As per feedback in https://github.com/ipfs/pinning-services-api-spec/issues/18#issuecomment-656781388 --- ipfs-pinning-service.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index b1c188f..2fb4666 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -51,9 +51,15 @@ Pinning Services are encouraged to add support for additional features by leveraging optional `meta` attributes: - `PinStatus.meta[progress]` – % progress of ongoing pinning operation + +- `PinStatus.meta[receivers] = ['multiaddr1','multiaddr2']` list of peers to connect to to speed up transfer of pinned data + - `Pin.meta[replication]` – could define how many copies service should keep + - `Pin.meta[depth]` – could define how deep the DAG should be pinned +- `Pin.meta[providers] = ['multiaddr1','multiaddr2']` list of peers that are known to have pinned data + Those can be vendor-specific, but we encourrage community to leverage `meta` to come up with conventions that could become part of mandatory revisions of this API. From d564a40eb2c0cac5326d19ddf4803a4e8c25c826 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 22:15:21 +0200 Subject: [PATCH 3/7] Remove Pin.meta[depth] example As per feedback in https://github.com/ipfs/pinning-services-api-spec/pull/19#discussion_r453685376 --- ipfs-pinning-service.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index 2fb4666..e2b5104 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -56,8 +56,6 @@ leveraging optional `meta` attributes: - `Pin.meta[replication]` – could define how many copies service should keep -- `Pin.meta[depth]` – could define how deep the DAG should be pinned - - `Pin.meta[providers] = ['multiaddr1','multiaddr2']` list of peers that are known to have pinned data Those can be vendor-specific, but we encourrage community to leverage `meta` to From a083f30b85c7f1c3bcf32d76d0bc7d8cef61db0a Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 22:29:17 +0200 Subject: [PATCH 4/7] PinStatus.meta examples: progress, fail_reason As per https://github.com/ipfs/pinning-services-api-spec/pull/19#discussion_r453702492 --- ipfs-pinning-service.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index e2b5104..d68df0e 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -50,7 +50,9 @@ Pin object can be removed via `DELETE /pins/{cid-of-pin-object}` Pinning Services are encouraged to add support for additional features by leveraging optional `meta` attributes: -- `PinStatus.meta[progress]` – % progress of ongoing pinning operation +- `PinStatus.meta[progress]` – % progress of ongoing pinning operation (if possible to tell) + +- `PinStatus.meta[fail_reason]` - service-specific reason why pin operation failed (eg. lack of funds, DAG too big etc) - `PinStatus.meta[receivers] = ['multiaddr1','multiaddr2']` list of peers to connect to to speed up transfer of pinned data @@ -255,7 +257,7 @@ components: - resolving # pinning in-progress: verifying pin request and looking for providers - retrieving # pinning in-progress: connected to at least one provider and fetched at least one block - pinned # pinned successfully - - failed # pining service was unable to finish pinning operation + - failed # pining service was unable to finish pinning operation, additional details can be foun in meta[fail_reason] - expired # (optional) still pinned for some time, but run out of funds and won't be provided to the IPFS network - unpinning # (optional) unpinning in-progress From 562be287e03898905944dbb8f664e2772ea42be2 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 22:31:08 +0200 Subject: [PATCH 5/7] Update ipfs-pinning-service.yaml Co-authored-by: Jacob Heun --- ipfs-pinning-service.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index d68df0e..9965675 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -60,7 +60,7 @@ leveraging optional `meta` attributes: - `Pin.meta[providers] = ['multiaddr1','multiaddr2']` list of peers that are known to have pinned data -Those can be vendor-specific, but we encourrage community to leverage `meta` to +Those can be vendor-specific, but we encourage community to leverage `meta` to come up with conventions that could become part of mandatory revisions of this API. From 02b49c01e4e9a4a5535423fe6a43d26b6cd56fb1 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 22:33:35 +0200 Subject: [PATCH 6/7] Update ipfs-pinning-service.yaml --- ipfs-pinning-service.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index 9965675..80910a9 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -257,7 +257,7 @@ components: - resolving # pinning in-progress: verifying pin request and looking for providers - retrieving # pinning in-progress: connected to at least one provider and fetched at least one block - pinned # pinned successfully - - failed # pining service was unable to finish pinning operation, additional details can be foun in meta[fail_reason] + - failed # pining service was unable to finish pinning operation, details can be found in meta[fail_reason] - expired # (optional) still pinned for some time, but run out of funds and won't be provided to the IPFS network - unpinning # (optional) unpinning in-progress From c9fe147adca97a3e7234008cd4ed80b184ce736d Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 13 Jul 2020 22:52:06 +0200 Subject: [PATCH 7/7] Clarify meta attributes are optional --- ipfs-pinning-service.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index 80910a9..52ccabb 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -61,8 +61,11 @@ leveraging optional `meta` attributes: - `Pin.meta[providers] = ['multiaddr1','multiaddr2']` list of peers that are known to have pinned data Those can be vendor-specific, but we encourage community to leverage `meta` to -come up with conventions that could become part of mandatory revisions of this -API. +come up with conventions that could become part of future revisions of this +API. + +It is ok to ommit or ignore `meta` attributes. +Doing so should not impact the basic pinning functionality. # Authorization