Response codes

[andrew]

One small detail I noticed in the spec is that for creating, modifying and deleting pins a successful response has a 202 code (accepted), which is described as:

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

I guess it's assumed that the pinning/deleting will happen outside of the request in a queue?

In my initial implementation there is no queue (responses can take a few seconds) so 202 feels wrong here, there's no need for the client to come back and check because the status will be pinned or failed in the response itself, so it makes sense for it to be a 200.

Similarly with deleting, the delete happens during the request so a 204 seems like the right response code here as there's no response body expected.

I wonder if there's some wiggle room in the spec for different response status codes depending on implementation, clients could definitely use the hint of 202 if they are going to need to come back and check on the status, although a status of queued or pinning also confirms that.

Related but possibly not helpful: looking at the status codes for the IPFS HTTP API, IPFS itself uses 200 when processing:

200 - The request was processed or is being processed (streaming)

[lidel]

IPFS HTTP API, IPFS itself uses 200 when processing:

The HTTP API under /api/v0/ is an RPC-style API over HTTP, not a REST API. Would not use it as inspiration. It does not support asynchronous mode of operation at all (either returns final response of uses streaming, which is blocking too), and due to RPC nature is very opinionated about codes (eg. returns 500 when it "should" return 404 etc).

I guess it's assumed that the pinning/deleting will happen outside of the request in a queue?

@andrew correct, the idea behind HTTP 202 is to emphasize the asynchronous nature of pinning operation.

Example: user should be able to create Pin object for a CID that represents 650GB of data (eg. ipfs files stat /ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco) and POST /pins should return immediately, with PinStatus.status set to queeued (no blocking)

For the simplicity, v0.0.5 of the spec returns 202 for both create and delete, even if pinned data was already on the pinning service. We could expand the spec and add support for returning 200 or even more correct 201 (created) for situation when pin was instantly created, without queuing, but it's already possible to indicate that by returning pinned in PinStatus.status, so its mostly cosmetic change, not sure if worth complicating HTTP client side.

Thoughts?

[andrew]

Yeah probably not worth complicating the spec over it at this point, plus I suspect that most http clients will just accept any old 2XX response and look at the status (which could possibly be a 2XX with failed) anyway, thanks for the thoughtful response 👍