Clarify requirements for JSON responses

[jamessynge]

Bob D. and I met at SAS and found that his Alpyca library couldn't handle the responses my TinyAlpacaServer produced. In particular, I omitted the ErrorNumber and ErrorMessage properties in the JSON body if there was no error. I don't know if the spec has changed, or I misinterpreted it, but the current ASCOM Alpaca Device API does clearly state that these properties should be present when there is no error.

However, the ASCOM Alpaca API Reference (pdf) uses the word should rather than must (actually, it says "should1"; I can't tell if that is for a footnote I can't find or a typo).

2.7 JSON Responses

The outcome of the command is returned in JSON encoded form. The following information should1
always be returned in every transaction response that has an HTTP 200 status:

[Peter-Simpson]

Hi James,

The extraneous 1 is a typo, which I will correct in the next update, thanks for reporting it.

I made those fields SHOULD because they aren't always relevant. For example, a ClientTransactionID may not have been provided by the client or an error may not have occurred. Personally, I always include these fields having defined them as part of a base class that is inherited by all data classes that hold returned data.

I think the document confusion is because we tightened up the specification to avoid situations, such as the one that you have found yourself in, but I missed that statement in the API reference, which should have been changed to a MUST instead of a SHOULD.

The primary reason for tightening the specification was to reduce ambiguity and enable clients to use intolerant JSON parsers that expect all elements to be returned. I started out being comfortable with Postel's Principle (Robustness Principle) but have grown to think that a less tolerant approach can have benefits because it prevents unwritten "common usage" developing that may hinder interoperation and reduce adoption of the API.

Best wishes, Peter