-
Type: Bug
-
Status: Closed
-
Priority: Major
-
Resolution: Won't Fix
-
Labels:
-
Environment:
Normative
-
Proposal:
When writing normative text, it isn't necessary and can be confusing to use RFC2119 control language.
Compare:
2.5. Service Provider: Suspend Operator
"Suspend the given Operator’s ability to create new Consumers and assign devices."
Exactly what you want, it's just a fact.
Whereas:
"If successful, an HTTP status code of 200 OK MUST be returned."
???
Why not:
2.5.2 Responses to Suspend Operator
2.5.2.1 HTTP status code of 200 OK
An HTTP status code of 200 OK indicates the operation was successful
2.5.2.2 HTTP error code or JSON object with explanation
An HTTP error code or a JSON object with explanation of failure indicates the operation failed.
By defining it this way (and moving MUST/SHOULD, etc. to the conformance clause) we note the failure operation IS INCOMPLETE.
What is the status with no response? That is the suspend operator was sent but there was no 200 OK and there was no HTTP error code or JSON object? What then?