Skip to main content
Adopt

IPA-127: Declarative-Friendly Interfaces

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​

  1. A resource must be strongly consistent with the Resource-Oriented Design (IPA-101).

    paths:
      /projects:
        get:
          operationId: listProjects
        post:
          operationId: createProject
      /projects/{projectId}:
        get:
          operationId: getProject
        delete:
          operationId: deleteProject
    Why:

    Paths form a noun hierarchy and each verb maps to a standard method on the resource, so the resource can be expressed as a desired state rather than a sequence of actions.

    paths:
      /createProject:
        post:
          operationId: createProject
      /deleteProjectById:
        post:
          operationId: deleteProjectById
    Why:

    The paths name actions instead of a resource. An action-shaped interface cannot be reconciled to a desired state, which is what IaC tooling depends on.

    1. Enumerate every entry under paths and group the paths by their resource segment.

    2. Confirm each path alternates collection nouns and resource identifiers rather than encoding a verb or action.

    3. Confirm each operation maps to a standard method on its resource (the verb matches the resource semantics, not an arbitrary RPC).

    4. Report any path or operation that models an action instead of a resource as a deviation from Resource-Oriented Design.

  2. A resource must have CREATE, DELETE, GET, and LIST methods.

    paths:
      /orders:
        get:
          operationId: listOrders
        post:
          operationId: createOrder
      /orders/{orderId}:
        get:
          operationId: getOrder
        delete:
          operationId: deleteOrder
    Why:

    The collection exposes LIST and CREATE and the item exposes GET and DELETE, so the full lifecycle of the resource can be driven declaratively.

    paths:
      /orders:
        post:
          operationId: createOrder
      /orders/{orderId}:
        get:
          operationId: getOrder
    Why:

    LIST and DELETE are missing. Without LIST, an IaC tool cannot discover existing resources to reconcile; without DELETE, removed configuration cannot be applied.

    1. Group the paths by resource: a collection path and its corresponding item path with a path parameter.

    2. For each resource, collect the operations on the collection path (get for LIST, post for CREATE) and on the item path (get for GET, delete for DELETE).

    3. Confirm all four standard methods are present for the resource.

    4. Report any resource that is missing one or more of CREATE, DELETE, GET, or LIST, unless it qualifies as a singleton or read-only resource.

  3. Singleton resources and read-only resources must have GET and LIST methods.

    paths:
      /audit-events:
        get:
          operationId: listAuditEvents
      /audit-events/{eventId}:
        get:
          operationId: getAuditEvent
    Why:

    Audit events are read-only, so the resource correctly exposes only GET and LIST and omits the mutating methods that do not apply.

    paths:
      /audit-events:
        post:
          operationId: createAuditEvent
      /audit-events/{eventId}:
        delete:
          operationId: deleteAuditEvent
    Why:

    A read-only resource exposes mutating methods and omits GET and LIST. The required read methods are absent, and the mutating methods imply a lifecycle the resource does not have.

    1. Identify resources that are singletons (no collection path with a list operation, accessed at a fixed path) or read-only (state is server-owned and not client-mutable).

    2. For each such resource, confirm a GET method is present (get on the item path) and a LIST method is present (get on the collection path).

    3. Confirm no mutating methods (CREATE, DELETE) are exposed where the resource cannot be created or removed by the client.

    4. Report any singleton or read-only resource that is missing GET or LIST.

    Depends on
    IPA 127: Must Have Standard Methods

  4. 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.

    paths:
      /jobs:
        post:
          operationId: createJob
      /jobs/{jobId}:
        get:
          operationId: getJob
        patch:
          operationId: updateJob
    Why:

    State that would otherwise be set by a custom action is modeled as a standard update, so the resource can be reconciled to a desired state by an IaC tool.

    paths:
      /jobs/{jobId}:
        get:
          operationId: getJob
      "/jobs/{jobId}:cancel":
        post:
          operationId: cancelJob
    Why:

    cancel is a custom method expressing an action rather than a state. IaC tooling cannot represent invoking an action, so this behavior falls outside automation.

    1. Enumerate the operations under paths and identify any custom methods, such as a path segment of the form :verb or an operation that does not map to a standard CREATE, READ, UPDATE, DELETE, or LIST method.

    2. For each custom method, determine whether the same outcome could be expressed as a state change on a standard method (for example, a status field updated via PATCH).

    3. Flag every custom method on a resource. Each occurrence is a deviation that requires explicit 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​