Skip to main content

IPA-5: Documenting Exceptions to IPAs

Following IPAs may not be possible for historical or technical reasons. For such cases it is important to make all API producers and consumers aware when an IPA can’t be followed to first avoid further adoption and second, capture the reasoning and history for the offending APIs.

State

Adopt

Guidance​

  • API producers must document within the OpenAPI spec when “should” or “must” guidance in an IPA is intentionally ignored to avoid unintentionally setting the wrong precedent for design
  • API producers must document the exception at the appropriate level within the OpenAPI spec to align with the scope of the rule being enforced
    • For example:
      • If the rule applies to an operation, the extension should be added to the operation definition
    • OpenAPI spec components where exceptions can be defined include but not limited to:
      • Operation
      • Parameter
      • Schema
      • Response
      • Request Body

Exception Format​

  • API producers must adhere to a key-value format.
    • Each key represents the IPA rule name, and the value provides the corresponding justification.
    • The key must start with xgen-IPA- prefix
    • API producers must provide a clear and concise explanation for why the exception is being applied
      • Exception justification must start with an upper-case letter and end with a full stop (.)
    • For exceptions related to IPA validation rules:
      • API producers must provide the exception key in the format: xgen-IPA-<IPA-principle-number>-{rule-name} with a valid rule name. Refer to the list of IPA validation rules for guidance.
    • For exceptions related to unlintable IPA guidelines:
      • API producers must provide the exception key in the format: xgen-IPA-<IPA-principle-number>
      • API producers must specify which guideline the exception is for in the exception justification
  • API producer may define multiple exceptions at the same level if needed

Example

{
  "x-xgen-IPA-exception": {
    "xgen-IPA-104-resource-has-GET": "Legacy API, not used by infrastructure-as-code tooling",
    "xgen-IPA-105-resource-has-LIST": "Legacy API, not used by infrastructure-as-code tooling"
  }
}

Local Consistency​

  • If a set of functionality doesn’t adhere to an IPA, it can be confusing for new functionality to break the existing pattern for the sake of adhering to IPAs. API producers should prefer consistency and document the exception

Pre-existing Functionality​

  • Features may be released before an IPA becomes standard, API producers should still document the exception