refactor: rename PinStatus id → requestid

[lidel]

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 👍 / 👎)

[hsanjuan]

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]

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]

I saw pid and immediately thought process id

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

[jessicaschilling]

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

[lidel]

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

[obo20]

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]

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.