HTTP 200 vs. 201 response for timestamps?

[delfuego]

Can I ask a dumb question — is there any stomach for perhaps adding an option to respond to timestamp requests with an HTTP 200 rather than 201?

I am actually embarrassed to be asking this, because I strongly believe that an HTTP 201 response is not just valid, but probably is in fact the semantically-correct response to send. But I'm in the unfortunate position of using a PDF-generating SDK that, when it tries to include timestamps in documents, will only accept an HTTP 200 response and reports failure when it receives an HTTP 201. (Yes, I'm surprised by this, and yes, their engineers have confirmed this for me.) I am in the midst of a reasoned discussion with them about how I think that the SDK's behavior is incorrect and that they should definitely consider 201 responses no differently than they currently consider and handle HTTP 200 responses... but I have no idea how successful I'll be. And I figured it was worth coming here and asking.

This is another place where, if I knew Go at all, I'd happily submit a PR for this for consideration... :/

[jku]

FWIW it does feel like 200 is more correct here: while a timestamp is indeed "created", I don't think the timestamp is an actual "resource" in the sense that HTTP refers to (it's just the response content).

Whether sigstore/timestamp-authority wants to change this behaviour now is of course another question -- no doubt some other software is now expecting 201 specifically. If the major TSA implementations all use 200 I think switching may still make sense.

[haydentherapper]

I agree, 200 seems more correct here. 201s are also returned for Fulcio, our stateless CA, that issues certificates but will not provide a resource path for later fetching those certificates, so it seems like 200 would be more accurate there as well.

Unfortunately, I think this would be a bit of a big change to make at the moment. I'll leave this issue open to track changing this in a v2 rewrite.

There might be a way to support this in the current codebase as a server configuration, but I'm not sure how easy it is to override the response code which is set in OpenAPI. In a v2 rewrite, I'd plan to migrate off OpenAPI, it's overkill for a simple service.

[delfuego]

Thanks for the consideration. I dove down that rabbit hole a bit and noticed that the response code was being set in the swagger-generated file from the OpenAPI definition, and that was basically where I realized that I would be in way over my head if I tried change it. 🤣

As it stands, I think I should be able to stand up a simple reverse proxy that rewrites the response code from 201 to 200 and otherwise passes the response through untouched; without doing this, there's no way for me to continue with the plan to use timestamp-authority with the Apryse PDF SDK; it hard-fails with the 201. (But on the plus side, they've now officially acknowledged a "feature request" (not bug report, alas) to handle HTTP 201 responses... but who knows when that might happen on their end.

[haydentherapper]

It looks like OpenAPI v2 doesn't support multiple response codes, so until we do more of a rewrite or make a breaking change, we'll continue to return 201s for now.

[delfuego]

Yeah, I've been deep in those OpenAPI weeds before.

If you're at all interested, one fairly low-lift way that you could support returning 200s with the current version and architecture is to add another endpoint with the literal exact same functionality except returning HTTP 200 (and with the OpenAPI definition specifying 200 so that that makes its way into the generated artifacts from which the proper response is surfaced). And then put this other endpoint behind a command-line flag (perhaps similar to the way you have the --http-ping-only flag that restricts the API to just the ping endpoint).

But literally, zero pressure on this.