Does the protocol spec govern exact status codes?

[RubenVerborgh]

[gibsonf1]

We for sure would prefer mandated codes to return in all cases to reduce head-scratching about what to send.

[kjetilk]

I say "sometimes we do, sometimes we don't". :-)

In the case of successful requests with no content, there are quite a few to choose from, 200, 204 and 205, and it is quite OK to use either. For resources that has just been created, it is best practice to use 201, but you could use one of the above too. It makes sense to be quite lenient.

In other cases, it would be just require a lot of extra effort on the implementers to find the right one, and I think that we should provide them with this.

Also of concern is that other specs should generally just need to reference the protocol spec for HTTP-specific stuff, and that includes the status codes, and so, I think in many cases, it makes sense to be clear about it.

[acoburn]

I would be careful about over-specifying such things. Providing guidance is great, but if the Solid protocol is combined with other, future, specifications, there may be cases where you encounter conflicts. For instance, Solid may require a 204 while another spec may require a 205. It is much better to require a 2xx response and recommend a particular code. The same applies to 4xx category codes.

[gibsonf1]

@acoburn I think a recommendation would be fine too, just getting some precise guidance would save dev time and create a more consistent ecosystem for apps to talk to.

[csarven]

The Solid Protocol works within the framework of HTTP (RFCs). The Protocol either tries to consistently echo RFC codes or recommends particular codes ones when describing specific behaviour. And there may potentially be wilful violations, but that tends to happen as a last resort in specific context when building on other (non-RFC) specifications.

It is worthwhile for the Protocol to allow sufficient variance so that implementations can accommodate specific needs without jeopardising interoperability. A conforming implementation follows the requirements trail all the way to the end.

I agree with concerns on extensibility and avoiding conflicts when specifications are combined.

#14 (comment) (WIP) hints at using codes sensibly (before the tables) eg. "Then, 2xx or 4xx (besides 401, 403) can be used." I consider the codes in the table as good/safe for implementations - but they shouldn't be taken as fixed and only way to achieve conformance. Some of those cases can legitimately use different codes. The original purpose of the table was to highlight "least information leakage" eg. 403 is perfectly fine/useful when need to raise forbidden, whether that's due to access controls, identifiers, or something else. But that doesn't mean implementations can't for example use 404. The comment in fact highlights when 404 may even be more interesting/useful of a response than a 403 in some cases (if the server chooses).

This applies to 3xx as well. We say 307, 308 when we really need to, but in the general case, 301, 302, 307, 308 for example, would be acceptable.

Depending on context, 200, 201, 204, 205 may be most appropriate but 202 and 203 would also be acceptable. The first set of codes is relatively more specific to the operation than the second set of codes.

We could list all valid codes but we'll just be repeating other specifications. Prefer to keep the Protocol lean. Follow DRY.. avoid potential mistakes..

Besides the case of requiring particular codes for specific behaviour, the Protocol should note that implementations (servers) use the most appropriate code within the boundaries of relevant specifications. This is already implied (IMHO) but okay to note. Ditto clients and applications expecting relevant codes. The Protocol should not note that any 2xx, 3xx, 4xx, 5xx is appropriate at all times - easy to fall into this trap.

[jeff-zucker]

Here's some implementation information based on Solid-Shell scripts run against CSS, NSS, ESS, and Solid-Rest. This is by no means exhaustive. Success was only tested when no pre-existing resources existed.

These are different between the servers:

CSS  NSS  ESS  Solid-Rest
205  201  201  201        PUT success
403  403  400  403        POST to auxiliary resource
205  200  204  200        PATCH success
205  409  204  409        PATCH delete non-existent triple  <-- someone is wrong
409  500  204  409        PATCH container                   <-- someone is wrong
205  200  204  200        DELETE success

These are the same in all four implementations

  200 GET on success
  200 HEAD on success
  201 POST on success
  204 OPTIONS on success
  400 PUT/POST/PATCH on no content-type supplied
  400 PATCH on syntax error in patch
  400 PATCH on syntax error in resource to be patched
  404 DELETE/GET/HEAD on item not found
  409 DELETE on container not empty

[kjetilk]

I'm not sure this issue serves a purpose. There are most certainly cases where valid status codes will be enumerated, and there are cases where the details are covered by e.g. HTTP RFCs. I'm not sure what else would be actionable from this issue.

[jeff-zucker]

Perhaps not much of an issue for spec writers, but really helpful for implementer to know. May I suggest that whenever a specific code or one of several codes is required, that it be so stated and when any 2xx response is okay, that also be stated. And what would be really helpful is a single page somewhere listing all of these that have been decided so that implementers are not left to pick through dozens of issues to figure out what is expected.

[kjetilk]

Yeah, I certainly recognize that, and since test suite will necessarily contain those status codes, there will be an authoritative source for them.

My hunch (having written a lot of the NSS implementation) is that that will be sufficient, you go with what is intuitive to you until a test fails, then you check out why it failed, and you'll see the authoritative answer at that point. I hope the spec won't be so weird there will a lot of exceptions from general intuition of devs :-)

If that expectation fails, there are three approaches, 1) fix the spec to align with developer intuition, 2) Just spec out all the weirdness in the spec clearly and 3) create a best practices document with all the status code. Or perhaps a mix of them. I think 1) would be quite appropriate. :-)