Skip to main content

IPA-127: Declarative-Friendly Interfaces

State

Adopt

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, a user defines what the resource should look like via an IaC tool, while the tool and underlying API take 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.\

Important

In addition to the existing guidelines, declarative-friendly interfaces require extra, stricter guidance to support IaC tooling automation.

Guidance​

  • A resource must be strongly consistent with the Resource-Oriented Design (IPA-101)
  • A resource must have CREATE, DELETE, GET, LIST methods, except for singleton resources and read-only resources which must have GET and LIST methods.
  • A resource should not have custom methods (IPA-109). Any complementary functionality of a resource exposed through custom methods will not be supported through automation. Deviation from this guidance requires a strong justification and review by the governing API body.

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.

Further Reading​