View on GitHub
Jobs and filters
Welcome to the third 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.
This month, we have one new AIP, which is around jobs: resources created for managing a task that may be repeated. We also have one AIP from April that we have delayed finalizing.
As always, the AIP newsletter kicks off what is effectively a "public comment" period: the AIP editors are happy with these proposals, but we want to ensure that you are too. Assuming feedback is sufficiently positive, we intend to formally approve these proposals on Friday, May 29, 2020.
AIPs under review
AIP-152: Jobs
Occasionally, APIs may need to expose a task that takes significant time to complete, and where a transient long-running operation is not appropriate. For example, a task could need to run repeatedly, or have separate permissions for configuring the task as opposed to running it.
Jobs are resources that are created that represent a (usually) repeated task in an API. The idea is that the job is configured once, and exists as an independent resource, which can either be executed by a user, or by the system on a schedule.
Jobs are useful when more structure or more permanence is needed than a simple RPC with a long-running operation can provide. They can also be useful if a service requires a permission model that distinguishes between who can configure a job as opposed to who can run it.
Summary: AIP-152 provides patterns for jobs: first-class resources that represent tasks that are run repeatedly, whether by a user or by the system on a schedule.
We are aiming to approve AIP-152 on May 29. If you have feedback, please leave a comment.
AIP-160: Filtering
Often, when listing resources, it is desirable to filter over the collection and only return results that the user is interested in.
Filtering involves taking a list of resources (usually) and only providing the results that the user wants, specified using a familiar syntax similar to that of Google search.
This AIP is a holdover from last month's newsletter: we intended to approve it in April, but several teams brought forth issues and clarifications that necessitated further iteration. (Thanks!!) These are now represented in the approval pull request (#473), and we hope to approve this AIP in May.
Summary: AIP-160 offers a detailed breakdown of the filtering syntax and how to provide filtering results in list and search methods.
We are aiming to approve AIP-160 on May 29. If you have feedback, please leave a comment.
Recent updates
In addition to the new AIPs under review, we have added the following guidance to existing AIPs: