From a3db8e13395e212627db2b4bd9e7d48cec9182b3 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 10 Sep 2020 14:02:15 +0200 Subject: [PATCH] docs: explain why replace operation is useful https://github.com/ipfs/pinning-services-api-spec/pull/61#pullrequestreview-485826723 --- ipfs-pinning-service.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index f7c2675..92254de 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -77,7 +77,7 @@ In this case, the user can periodically check pinning progress via `GET /pins/{i ### Replacing an existing pin object -The user can replace an existing pin object via `POST /pins/{id}`. This is a shortcut for removing a pin object identified by `id` and creating a new one in a single API call. The new pin object `id` is returned in the `PinStatus` response. The old pin object is deleted automatically. +The user can replace an existing pin object via `POST /pins/{id}`. This is a shortcut for removing a pin object identified by `id` and creating a new one in a single API call that protects against undesired garbage collection of blocks common to both pins. Useful when updating a pin representing a huge dataset where most of blocks did not change. The new pin object `id` is returned in the `PinStatus` response. The old pin object is deleted automatically. ### Removing a pin object @@ -256,7 +256,7 @@ paths: $ref: '#/components/responses/InternalServerError' post: summary: Replace pin object - description: Replace an existing pin object (shortcut for executing both remove and add in one step) + description: Replace an existing pin object (shortcut for executing remove and add operations in one step to avoid unnecessary garbage collection of blocks present in both recursive pins) tags: - pins requestBody: