Apply feedback from Pinning Summit

[lidel]

A small iteration happened during workshop at Pinning Summit, May 7th, 2020.

We should update ipfs-pinning-service.yaml if needed, or document why it is out of scope of MVP.

type pin {
    cid: <cid>
    pin: <pin-type>
    meta: { // all of this is application specific
        created: <date>
        modified: <date>
        replication: ...
}
}

GET         /pins                     -- lists all pins
GET         /pins/?for-cid={cid}      -- get all pins that link to {cid}
POST         /pins                     -- add an array of pin objects
GET         /pins/{cid-of-pin-object} -- get pin object
DELETE     /pins/{cid-of-pin-object} -- deletes pin object
POST        /pins/{cid-of-pin-object} -- updates pin object

Questions:

• Is there any additional metadata you think MUST be in the Pin object?
• Is there any additional API/RPC endpoint for this simple Pin API that MUST be there?

[obo20]

Looking through this, a few questions:

1) For the GET /pins endpoint: is there any filtering that you would expect here? Pagination? Is this expect to list CIDs for content that was previously pinned but is now unpinned or just currently pinned CIDs?

2) For GET /pins/?for-cid={cid}: This sort of goes with my previous question, but is there ever a situation where you would expect multiple entities to be returned here? If so, could you explain what this endpoints response will look like?

3) What sort of "updates" should the POST /pins/{cid-of-pin-object} be doing?

[lidel]

@obo20 apologies for missing this one! (I suspect GH notificaiton bug)

1. I believe by default GET /pins returns only currently pinned CIDs.
   Pagination is an open question – tracked separately in #12, but could be tackled as subset of filtering, which is also an open question – so far we would have ?for-cid=, but more can be added, if we decide to make more fields mandatory.

   • Q: Is there any additional metadata you think MUST be in the Pin object?
     • @obo20 do you have any stats on how popular filters in your PinList API are? That could inform what types of filters should be present in the first iteration of this API. Adding filtering by fields like pin-type created modified would make them mandatory. No requirement to keep history atm, but in theory we can add timestamp removed in the future and add opt-in filter that returns unpinned items.

2. GET /pins/?for-cid={cid} Potential scenario is when you pin the same cid from different devices or apps, and that produces different meta values. Response would be multiple pin objects, all pointing at the same cid but having different meta or pin-type. With that, apps could decide to include appid in meta and use that hint to show/manage/premove only own pins.

3. POST /pins/{cid-of-pin-object} would be used for modifying attributes of existing pins. Behind the scenes old pin is removed and replaced with the new, modified verison (analog to ipfs pin update). Example use case: WebUI constantly updating recursive pin for MFS root.

I'll prepare PR that updates spec to the Pinning Summit version later today.

[obo20]

@lidel thanks for the response.

1. Returning only currently pinned CIDs works fine for us. In terms of filtering, unfortunately we're not tracking individual filter queries right now so we don't have data on what people are utilizing here.

2. If the same object gets pinned to Pinata twice, we actually "ignore" that second request as the user already has the object pinned in our system. All the metadata for this object stays the same as the original pin instance. So in our system, this endpoint would only ever return one instance per CID. The intention behind this design choice was to prevent people from accidentally uploading something twice from multiple devices and getting charged multiple times for it.

3. How are you expecting this to work from a data linking standpoint? We can certainly unpin an old CID and pin a new one to our system, but we don't have a way to "link" new pins to old versions of the pins (so no historical git type functionality if that's what you're looking for). Users would simply see that their previous version was unpinned and the CID for their new object is now in their pinList. Would this work?

[lidel]

Update: implemented Pinning Summit variant in #14

1. Ack. I've added basic pagination and filtering by CID and depth. Please suggest any missing filters in https://github.com/ipfs/pinning-services-api-spec/pull/14, or fill an issue if you feel longer discussion is due, we could add them later

2. I am probably missing a lot of context, but hope that primitives proposed in https://github.com/ipfs/pinning-services-api-spec/pull/14 make it possible to avoid double charging. I imagine that when user is pinning a new thing, backend will internally list pin objects for specific CID, and if at least one pin object already exists, do not charge the user for this additional pin.

3. Should work. AFAIK there is no need for linking between versions here. This API exists mostly for convenience + opportunistic optimization of using things like more efficient pin update instead of pin add && pin rm (but it is not mandatory, up to pinning service to decide on backend details)