Details

    • Proposal:
      Hide

      Recast rules to normative prose and reserve RFC2119 keywords for the conformance clauses. (Plus fix the omitted case in 2.5)

      Show
      Recast rules to normative prose and reserve RFC2119 keywords for the conformance clauses. (Plus fix the omitted case in 2.5)

      Description

      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?

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              chet-oasis Chet Ensign
            • Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: