refactor: rename PinStatus id → requestid

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

refactor: rename PinStatus id → requestid #63

Closed lidel closed 4 years ago

lidel commented 4 years ago

This is an attempt to clarify the difference between cid identifier in request and id in response:

adds "Identifiers" section to the docs and clarifies purpose of each
BREAKING CHANGE: id is renamed to requestid
- I believe this will make it easier for people to reason requestid vs cid, but can restore old field name if community decides it is not worth the hassle.

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

cc @obo20 @andrew @aschmahmann @GregTheGreek @priom @jsign @sanderpick @andrewxhill @ipfs/wg-pinning-services

Please provide feedback (even if its just :+1: / :-1:)

hsanjuan commented 4 years ago

I would have thought pid corresponds to peerID (which incidentally looks like a CID), not PinID. For this reason it does not seem to me like the best name. Perhaps it does not hurt to be specific and name this requestid or trackid.

jacobheun commented 4 years ago

If we're going to rename it, +1 to requestid, just remove the ambiguity. I saw pid and immediately thought process id, so it's clear to me it's not really alleviating confusion.

andrew commented 4 years ago

I saw pid and immediately thought process id

+1 on that, also +1 on @hsanjuan's requestid

jessicaschilling commented 4 years ago

+1 to @jacobheun and @hsanjuan, plus "pid" has some unpleasant real-world meaning.

lidel commented 4 years ago

Thanks for quick feedback! renamed it to requestid (which indeed removes any surface for ambiguity) and updated PR to reflect the change

obo20 commented 4 years ago

Any thoughts on objectid, serviceid, or psid(pinning service id)?

requestid works for me, but it makes me immediately think of the api request itself which could be confusing to some people seeing as you may make multiple api requests to a single ID over its life cycle.

lidel commented 4 years ago

I think those are also fine, but requestid is tiny bit better as it enables us to explain things in simpler words:

Every (HTTP) request to create a pin object at a pinning service has a unique ID
You use this ID to check the status of ongoing pin request, and for revoking / replacing it later.