docs: clarify replace operation

ipfs / pinning-services-api-spec

Standalone, vendor-agnostic Pinning Service API for IPFS ecosystem

https://ipfs.github.io/pinning-services-api-spec/

Creative Commons Zero v1.0 Universal

99 stars 26 forks source link

docs: clarify replace operation #61

Closed lidel closed 4 years ago

lidel commented 4 years ago

This PR updates docs and renames "modify" operation with "replace":

"update" and "modify" do not describe what is actually happening.
"replace" should make it easier to reason about the purpose of this operation.

Preview: https://ipfs.github.io/pinning-services-api-spec/#specUrl=https://raw.githubusercontent.com/ipfs/pinning-services-api-spec/docs/replace-call/ipfs-pinning-service.yaml

lidel commented 4 years ago

@andrew good point!

Added notes about protecting against undersired garbage collection of data common to both old and new pin in a3db8e1 (feel free to tweak it if it could be worded better)

lidel commented 4 years ago

This is also a docs-only change, so merging