Skip to main content

IPA-127: Declarative-Friendly Interfaces

State

Experimental

Following declarative-friendly standards is essential for ensuring reliable, consistent, automated, and low-latency integrations with consumers, such as Infrastructure as Code (IaC) tools, which many customers heavily depend on for their DevOps workflows.
An interface is considered "declarative-friendly" when resources can be managed by specifying their desired final state, rather than outlining a series of steps or actions. In this approach, you define what the resource should look like, while the API takes care of the how.

With the wide range of popular IaC tools and the constant demand to integrate diverse resource types across multiple platforms, uniformity is critical to fully automating these integrations.
The following guidance is to enable interfaces to be declarative-friendly and support automation.

Guidance​

  • A resource must be strongly consistent with the Resource-Oriented Design (IPA-101)
    • An interface must expose the full resource lifecycle using standard HTTP verbs. The GET operation is critical for IaC tools to read the current state and compare it against the desired state.
  • A resource must have CREATE, DELETE, GET, LIST and UPDATE methods.
    • Response schemas of CREATE, GET and UPDATE must be the same
    • Fields defined in CREATE and UPDATE request schemas should be the same and should be present in response schema
    • For full guidance, see IPA-103, IPA-104, IPA-105, IPA-106, IPA-107, IPA-108
  • A resource must not have custom methods (IPA-109) as they make some automations impossible. Any deviation from this guidance requires a strong justification and review by the governing API body.
  • A resource field must have a single owner (IPA-111)
    • Effective fields must be used when a client-owned field can also be controlled by the server
  • A resource field name must be consistent in between the request, response body and path parameters (IPA-112)
  • A resource must have a standardized error format so that consumers can fully rely on understandable API responses (IPA-114)
  • A resource field should have a single type (IPA-125)

Motivation and Strategic Goals​

Our engineering teams and customers rely on IaC tools to manage infrastructure repeatably and reliably. APIs that don't follow a declarative model require complex and brittle integration work, creating a poor experience for all consumers.

The primary strategic benefit of adopting a consistent declarative model is the ability to automate the generation of IaC provider resources. When our APIs are predictably declarative, we can build automations that create and maintain tools such as our Terraform and CloudFormation providers. This will dramatically accelerate the availability of IaC support for our products and reduce manual, error-prone development.