v0.0.2: Pinning Summit + initial feedback

[lidel]

This version is following spec drafted during Pinning Summit where we switched API to operate on "pin objects" with some improvements based on initial feedback and discussions received from the community this week.

This is by no means the finished spec: goal is to close some topics and kick-off discussions on remaining items.

Changes in this PR

:question: – needs clarification or further discussion ⁉️– potentially controversial

• [x] Changes from Pinning Summit, namely change API to operate on "pin objects" (closes #2)
  • [x] Replaced vendors-specific fields such as replicationParam with a free form meta
• [x] Basic pagination with skip and limit parameters (closes #12)
• [x] Added ability to filter pin objects using arrays of CIDs and/or statuses (closes #1)
• [x] :question: simplified authorization based on opaque string that can be passed in HTTP header or query param, as suggested by @mikeal in https://github.com/ipfs/pinning-services-api-spec/issues/6#issuecomment-655056961
• [x] Examples and missing descriptions
• [x] :question: Status enum in which pin object can exist at a pinning service (for now those are just strings)
• [x] ⁉️ replaced "pin type" with more flexible depth It can represent direct (0) and recursive (-1) pins just fine, but opens more advanced strategies in the future.
• ⁉️ GET /pins/?cid=Qm&depth=1 could return pin status of arbitrary subtree depth is just a simple filter (direct/recursive)

Documentation Preview

Docs for feat/pinning-summit-variant-v0.0.2 branch can be viewed at:

• https://bafybeibarvujzcxuqikzdb22pzdbza4hz4rdvaagrcunjs7zhaqamw46ku.ipfs.dweb.link/

cc @pooja @jacobheun @aschmahmann @achingbrain @autonome @gozala @momack2 @olizilla @obo20 @sanderpick

[obo20]

⁉️ replaced "pin type" with more flexible depth It can represent direct (0) and recursive (-1) pins just fine, but opens more advanced strategies in the future. ⁉️ GET /pins/?cid=Qm&depth=1 could return pin status of arbitrary subtree (open question: how to represent indirect pins in PinStatus object? add indirect Status enum?)

I'm not sure if filtering based on pin depth is possible right now. As far as I'm aware all current pinning services (including Pinata) only track pinned items by the root CID.

[lidel]

@obo20 fair enough, could be revisited in the future, if needed.

For now, I believe we should be ok with simplified depth filter (recursive/direct). As long cid filter accepts an array of CIDs to provide a way of addressing need described in #1

[aschmahmann]

This overall seems fine to me, although I've got a few thoughts/questions about pinning service flow and the pinning objects we're introducing here.

• My concern is that if users are expecting something like ipfs pin add --with-service=mypinner QmXYZ to immediately ship the data to the pinning service that we could run into problems if QmXYZ is not already published to the DHT
• This becomes worse with the pinning objects since we'll generate a new pin object that we'll have to wait for the DHT to finish providing before the pinning service can find the data. We'll likely want to not even send the HTTP request until the DHT put is completed
  • We can work around this by pre-connecting to a pinning service upload IPFS node, if that's available, but since my understanding was that having one of those was not a requirement for implementing this API it's a shame that users may have to wait for a DHT provide to finish before the pinning can start
  • If we expect users to have many different pin objects that they'll be providing to the network they could get bogged down in the provide queue. How many pin objects do we expect an "average" user to create if they are pinning N objects?
  • If we are able to send the pin object over HTTP then this problem basically goes away

[lidel]

@aschmahmann good catch! I failed to document that aspect, fixed now.

Pinned data may not be present at a pinning service and at the same time pin object creation should not be a blocking operation. User may be pinning big data set that takes time to transfer and we don't want CLI and other tools to hang. Instead of waiting for remote pinning to finish, cid-of-pin-object is returned immediately in PinStatus response, and can be used for periodical status checks later.

I've added Pin object lifecycle to the spec and missing PinStatus responses required for async status checks of ongoing pinning operations.

Pin status/progress check can be done via GET /pins/{cid-of-pin-object} or GET /pins?cid={cid-being-pinned}.

Q: how specific should the status reporting be?

Right now Status is an enum string with values like "pinning" vs "pinned", but I wonder if ability to return % value would be more flexible / useful for UIs here. Thoughts?

[jacobheun]

Right now Status is an enum string with values like "pinning" vs "pinned", but I wonder if ability to return % value would be more flexible / useful for UIs here. Thoughts?

I'd skip this for now. This could come back in the meta object for pins that are in progress.

[obo20]

Q: how specific should the status reporting be? Right now Status is an enum string with values like "pinning" vs "pinned", but I wonder if ability to return % value would be more flexible / useful for UIs here. Thoughts?

I don't think % pinned is currently possible, but we could certainly provide statuses that signify the object is currently being fetched. For reference, this are the current statuses we have in Pinata's system when pinning by CID.

• "prechecking" - Pinata is running preliminary validations on your pin request.
• "searching" - Pinata is actively searching for your content on the IPFS network. This may take some time if your content is isolated.
• "retrieving" - Pinata has located your content and is now in the process of retrieving it.
• "expired" - Pinata wasn't able to find your content after a day of searching the IPFS network. Please make sure your content is hosted on the IPFS network before trying to pin again.
• "over_free_limit" - Pinning this object would put you over the free tier limit. Please add a credit card to continue pinning content.
• "over_max_size" - This object is too large of an item to pin. If you're seeing this, please contact us for a more custom solution.
• "invalid_object" - The object you're attempting to pin isn't readable by IPFS nodes. Please contact us if you receive this, as we'd like to better understand what you're attempting to pin.
• "bad_host_node" - You provided a host node that was either invalid or unreachable. Please make sure all provided host nodes are online and reachable.

Obviously not all of these would apply to every service, but I do think it would be good to have a standard set of statuses that we can all agree on.