Listing of all applicable HTTP Status Codes

[cmheazel]

Requirement 38 - I question if this is feasible. Implementers should not be required to research and describe every status code which may be returned by the HTTP protocol. Many of these are artifacts of the network topology and HTTP protocol itself. It is feasible for implemeters to describe any status codes produced by their service which are not standard HTTP codes. I suspect that is the intent of the requirement. But without a specific definition of "service" as being the software logic accessible through the Base URL, this requirement is ambiguous.

[cportele]

By now this is no longer requirement 38. I think this refers to requirement /req/oas30/exceptions-codes (https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#exceptions).

I understand the comment and it would be good to have a good understanding what the general practice and expectations are in the OpenAPI community.

PS: To exclude errors raised in the transport between the server and the client by using the wording "error situations that originate from the server".

[akuckartz]

Such a listing of status codes should not be normative because they are specified in the HTTP specification(s). See https://tools.ietf.org/html/rfc7231#section-6

[cportele]

06-MAY-2019 Conference calls: Make it a recommendation. We ended up with: "The API definition SHOULD cover the HTTP error codes for each operation for error situations that originate from the API implementation. Note that error codes originating from the protocol level will not be included in the API definition, but still need to be handled by clients. This is implicit in the requirement for HTTP compliance." Chuck will make a proposal.

[akuckartz]

This seems to imply that "API implementation" != "protocol level"

I doubt that such a difference exists or should exist. But I will wait for the proposal.

[cportele]

@akuckartz - Yes, the notes were a bit brief. "Protocol level" here refers to anything between the API implementation and the client. For example a 504 created by a proxy. If the API implementation will never return a 504 for an operation this status code does not belong into the API definition of that operation, but clients still have to be prepared to receive a 504 (or any other undocumented status code). However, if the API implementation may return a 500, this should be documented in the API definition.

[cmheazel]

Please review and comment on pull request #223

[cmheazel]

Pull request has been updated. Added a paragraph on how the status codes should be advertised in the API Description Document.