Document behavior for indirect pins

[lidel]

Context: Ability to tell CID is pinned indirectly is somnething that we need for Pinning Service integration within IPFS Desktop and WebUI (ipfs/ipfs-gui#91).

It is possible to check pin status of a specific CID:

GET /pins?cid=Qmfoo

Returned PinStatus object includes pin object for recursive pin and a status:

pinning-services-api-spec/ipfs-pinning-service.yaml

Lines 303 to 310 in 13a817d

	Status:
	description: status a pin object can have at a pinning service
	type: string
	enum:
	- pinning # pinning in progress, optional details can be returned in meta[pinning_status]
	- pinned # pinned successfully
	- failed # pining service was unable to finish pinning operation, optional details can be found in meta[fail_reason]
	- unpinned # data is no longer pinned

Document behavior for indirect pins

Current spec does not specify what should be the response for a CID that is indirectly pinned (not pinned itself, but a member of a DAG that is recursively pinned).

Proposal

• I don't think we should add indirect status.
• Instead, asking for indirectly pinned CID should return Pin object that is responsible for keeping it around

Thoughts, concerns?

[jacobheun]

We previously nixed Pin.mode because it made sense for Pins to just be recursively created, however, for responses perhaps it would make sense to show Pin.mode as recursive of indirect. This would let us show indirection.

My concerns with returning the responsible Pin(s) are:

• How many responsible pins are returned? ipfs pin ls <cid> only returns one, but there could be any number of responsible pins. Showing just 1 could be confusing, and I don't like the idea of getting all of them at this point in time.
• If I request max limit pins from /pins, this would result in at least limit*2 pins.

Ideally I'd prefer to just do mode (type) at this point as it meets the needs and is a small change. meta could be used to show the responsible pin(s), but frankly I'd avoid that until we look more into supporting pin sets / threads.

[lidel]

I'm closing this for now: until the community raises need for explicit support of indirect pins, the API should simply ignore them. As suggested by @jacobheun above, let's park this until sets/threads are part of discussion.

This does not impact our MVP integration: our GUI will check CID of every item in current directory + every parent directory to detect indirect pins, making this no longer an urgent issue. I decreased priority accordingly.

Moreover, checking if a CID is part of one of pinned DAGs will be an expensive operation, and in #66 we want to avoid those.