Subject: [Acme] Consolidating API theory/principle/pattern information

From: Zach Shepherd <[email-masked]>
Date: Thu, 23 Mar 2017 19:54:23 +0000

The following feedback is based on 5acf62b (current HEAD of master).

Section 6, Message Transport, covers two distinct types of information:
* Information about Message Transport.
* High-level information about messages, but not their transport.

Section 7, Certificate Management, also covers two distinct types of information:
* Theory, guiding principles, and general patterns for the API.
* Definition of the concrete Certificate Management APIs.

I propose restructuring this document to extract a new section between Message Transport and Certificate Management containing the non-transport information from the Message Transport section and theory/principle/pattern information from the Certificate Management section.

This new section might contain subsections for:
* Section 6.5, Rate limits
* Section 6.6, Errors
* The directory pattern and high-level information about the use of link relations from Section 7.1, Resources
* The pagination pattern from Section 7.1.2.1, Orders List
* The requirement from Section 7.3, Account Creation, that "In general, the server MUST ignore any fields in the request object that it does not recognize." (Which seems related to the requirement from Section 7.5.1, Responding to Challenge, that "The server MUST ignore any fields in the response object that are not specified as response fields for this type of challenge.")
* The polling pattern used in Sections 7.4 and 7.5.1

This would give the overall document a flow along the lines of: Overview, Encoding, Transport, [New Section], Management, Challenges.

I believe this will improve the overall flow of the document, reduce duplication, and ensure consistency. Separating this information out is especially useful for ensuring that future extensions/additions/changes can easily refer to and follow existing theory/principles/patterns. Providing this information in its own section instead of in a "just in time" fashion is also useful for helping new readers build a correct mental model up front, before diving into the Certificate Management information.

I have chosen not to propose a name for this new section; I believe that it would be hard to select an appropriate name without consensus on the scope/content of the section.

Regards,
Zach Shepherd