Declarative-friendly APIs

Welcome to the sixth edition of the AIP newsletter, which is designed to keep you up to date about the AIP program, and particular proposals making their way through the system.

We have an exciting slate of AIPs entering review this cycle, all around the theme of "declarative-friendly APIs". The linchpin here is AIP-128, which introduces and explains the topic.

The idea behind declarative-friendly APIs addresses an important need: the ability to integrate with popular, declarative tools, such as Kubernetes or Terraform. These tools and others are used by numerous developers, and the follow a straightforward paradigm: the user provides the tool with the desired state, and the tool brings that state into fruition.

Integration with these tools is critical for cloud providers, but with the number of services and the number of tools continuously increasing, support is difficult without a reliance on automation. Automation, in turn, requires strong consistency.

While ordinarily AIPs stay in review for about a month, we intend for this review cycle to be longer, to allow time for APIs to be released that follow this guidance. Assuming the feedback is sufficiently positive, we will probably be looking at formal approval around the end of the year.

AIPs under review

AIP-128: Declarative-friendly interfaces

Many services need to interact with common DevOps tools, particularly those that create and manage network-addressible resources (such as virtual machines, load balancers, database instances, and so on). These tools revolve around the principle of "configuration as code": the user specifies the complete intended landscape, and tooling is responsible for making whatever changes are necessary to achieve the user's specification.

These tools are declarative: rather than specifying specific actions to take, they specify the desired outcome, with the actions being derived based on the differences between the current landscape and the intended one.

Declarative-friendly interfaces describes patterns for making interfaces that are friendly to automated tooling. The basic idea is that by being more strict and consistent, it becomes possible to write tools that "translate" the interface to a declarative form without having to know anything about the specific API.

This reduces feature latency for users. Essentially, the adapter or plugin can be automatically generated, and so an automated pipeline becomes possible: as soon as the service launches new features, they become available in the adapters also.

Because declarative-friendliness is a wide-ranging concept, impacting the guidance in numerous other AIPs as well, it was difficult to determine how to structure the information. Therefore, this AIP also has a robust "further reading" section that points to declarative-friendly guidance in other AIPs.

Summary: AIP-128 provides an explanation of what it means for a service to be declarative-friendly, and why a service might want to adopt these patterns. It also indexes declarative-friendly guidance found in other AIPs.

AIP-148: Standard fields

Certain concepts are common throughout any corpus of APIs. In these situations, it is useful to have a standard field name that is used consistently to communicate that concept.

Standard fields is, in some ways, an overdue AIP. It describes fields common throughout our corpus, such as name, parent, and create_time, that were on the list of standard fields in the original API style guide and did not get a full treatment in other AIPs. Common fields that are covered in other AIPs are not discussed in this one. (As an example, language_code is given extensive treatment in AIP-143, so not repeated here.)

This takes on new importance with our focus on declarative-friendly APIs because tools written to marshal between a declarative tool and the service can see those tools and know what they mean.

Summary: AIP-148 describes common fields that are already in common use throughout our API corpus. It also describes certain fields that are expected on declarative-friendly resources.

AIP-164: Soft delete

There are several reasons why a client could desire soft delete and undelete functionality, but one over-arching reason stands out: recovery from mistakes. A service that supports undelete makes it possible for users to recover resources that were deleted by accident.

Soft delete is increasingly critical for APIs that need to cater to enterprise users, due to the need to be able to recover from mistakes without data loss. While AIP-135 previously discussed soft delete, it was clear that a more thorough treatment is necessary.

This AIP goes through the request patterns in more detail, and discusses topics such as LROs and errata, that are relevant to soft delete and undelete.

Summary: AIP-164 expands the guidance on soft delete and undelete and provides a more detailed look at both.

AIP sections under review

Because of the need to add declarative-friendly guidance into existing AIPs, certain sections needed to be introduced into existing, approved AIPs in a reviewing state. These are all in use for declarative-friendly guidance and would be approved alongside AIP-128:

Additionally, new sections in AIP-154 and AIP-163 mandate the use of these concepts for declarative-friendly resources.

Recent updates

In addition to the new AIPs under review, we have added the following guidance to existing AIPs:

  • AIP-122: Clarified when to use full resource names (#629)
  • AIP-132: Loosened guidance around top-level resources (#602)
  • AIP-132: Added PERMISSION_DENIED guidance (#582)
  • AIP-151: Clarified that stream and LROs are mutually incompatible (#597)
  • AIP-216: Clarified that states are not directly set on Create (#606)

Special thanks to Andrew Paseltiner and Peter Novotney for some of these changes, and to several others who send minor corrections not noted here.