From 0e97a3878c7540361516f9859e34e315bae41a32 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 11 Sep 2020 20:30:44 +0200 Subject: [PATCH] docs: clarify replace operation (#61) Co-authored-by: Jessica Schilling --- ipfs-pinning-service.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml index f6c374b..bc18fa8 100644 --- a/ipfs-pinning-service.yaml +++ b/ipfs-pinning-service.yaml @@ -75,9 +75,9 @@ The user sends a `Pin` object to `POST /pins` and receives a `PinStatus` respons In this case, the user can periodically check pinning progress via `GET /pins/{id}` until pinning is successful, or the user decides to remove the pending pin. -### Modifying an existing pin object +### Replacing an existing pin object -The user can modify an existing pin object via `POST /pins/{id}`. 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 @@ -255,8 +255,8 @@ paths: '500': $ref: '#/components/responses/InternalServerError' post: - summary: Modify pin object - description: Modify an existing pin object + summary: Replace pin object + 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: