[Sandbox] API Improvement Proposals (AIP)

makahmad commented 1 year ago

Application contact emails

seyed.ahmad@gmail.com, davidebbo@google.com, yusuketsutsumi@google.com

Project Summary

API Improvement Proposals (AIP) are focused design documents for flexible API development

Project Description

In 2019, Google published their API standards, API Improvement Proposals (AIPs), externally on google.aip.dev. Starting 2020, an industry wide effort began with API enthusiasts in many companies (Google, Meta, Roblox, Microsoft, IBM, Oracle, Netflix, and Salesforce) to create API design guidelines now known as Core AIPs.

Drawing from lessons learned by experts from across the industry, Core AIPs specify patterns and practices for cloud APIs that have a great developer experience, are robust, secure, and scalable by design, support a variety of client integration paradigms, and provide evolutionary flexibility.

Org repo URL

https://github.com/aip-dev

Project repo URL

https://github.com/aip-dev/aip.dev

Additional repos

https://github.com/aip-dev/google.aip.dev (this would remain as these are Google specific AIPs and there’s numerous links to google.aip.dev from internal Google documents)

https://github.com/googleapis/api-linter

Website URL

aip.dev

Roadmap

See below

Roadmap context

For 2023, we are making a significant push toward widening the reach of the AIPs, and addressing known issues that make the standards and surrounding framework less usable. There have been a handful of enterprise adopters, but see several projects that are valuable to expand the reach of this standard. Specifically:

Performing a full audit of Google’s 30+ AIPs, generalizing them for readily consumption by an organization.
Improvements to the site-generator to allow customization without forking.
Improvements to the information architecture of the AIPs (enabling deeper explanations of rationale for standard decisions).
Refactor of aip.dev and the api-linter to the same repository, allowing code that enforces guidance to live closer to the written specification.
Expanding the api-linter framework to enable verification of more interface definitions beyond protobut (e.g. OpenAPIV3).

Contributing Guide

https://aip-dev.github.io/aip.dev/contributing (with the Google CLA removed)

Code of Conduct (CoC)

will adopt the CNCF CoC

Adopters

AIPs have been adopted at multiple companies such as Roblox and Salesforce however the URLs are not public.

Contributing or Sponsoring Org

Google

Maintainers file

https://github.com/aip-dev/aip.dev/graphs/contributors

IP Policy

[X] If the project is accepted, I agree the project will follow the CNCF IP Policy

Trademark and accounts

[X] If the project is accepted, I agree to donate all project trademarks and accounts to the CNCF

Why CNCF?

The API design guidelines that are, in many ways, universal. Besides being used at Google, many companies (Roblox, IBM, Meta, Microsoft, Salesforce, etc) have also adopted it for various teams. The best choice for long-term viability and independence of the API design guidelines is to centralize the API standards in a foundation, such as CNCF, to live among other Google donated projects such as Kubernetes and Istio.

Benefit to the Landscape

APIs are a fundamental part of the cloud-native ecosystem. Enabling API developers to reference good design guidelines will improve the API design production experience and consumption experience.

Our values are:

Approachability (easy to get started)
Usability (easy to build real world integrations)
Versatility (ability to support everything from simple automations, to graphical user interfaces, to comprehensibve declarative integrations)
Robustness (clear and consistent input validation, safe concurrent request support)
Scalability (individual operations don't become too expensive at scale)
Language and framework independence (API could be re-implemented on a different stack)
Evolutionary flexibility (API is designed to grow to support more features without breaking existing clients)

Cloud Native 'Fit'

API design is fundamental for any Cloud Native project. We feel that AIPs should be in the same foundation family as Kubernetes and Istio, as well as a companion to gRPC (incubating).

Cloud Native 'Integration'

Long term, we hope that AIPs can become the rich API standard that CNCF projects that expose APIs can adhere to (e.g. Kubernetes).

An API standard and validation toolkit is a great dependency for projects who want ease of integration into multiple categories of clients (CLIs, UIs, SDKs, and IaC tools) without the significant mental overhead of considering the concerns of each and every one. Scope could include CNCF-sponsored projects (e.g. simplifying integration for Backstage plugins).

Cloud Native Overlap

AIPs provide API guidance, which exists in some form in multiple CNCF projects (e.g. Kubernetes explains guidance around their resource model. similar to AIP's resource-oriented design).

Similar projects

Tactically, this project is similar to Microsoft’s REST guidelines and IBM Cloud’s API Handbook. Conceptually, this project is similar to OpenTelemetry: providing a common higher-order interface and semantics paired with an ecosystem of code generators, documentation, and integrations that can be used by API producers and consumers.

Product or Service to Project separation

N/A

Project presentations

Nope

Project champions

None

Additional information

No response

caniszczyk commented 1 year ago

very cool project @makahmad - are there any projects in CNCF using this yet?

is your goal to see more open source adoption of this?

toumorokoshi commented 1 year ago

very cool project @makahmad - are there any projects in CNCF using this yet?

is your goal to see more open source adoption of this?

Hello! I'm Yusuke, the third name attached.

are there any projects in CNCF using this yet?

No, I don't believe so. although the spec is refined for Google at the moment, we're actively working on generalizing the guidance at which point (not a lot if issues just tweaks on some names), and also OSS-ing some in-house tools created by the organizations mentioned above.

I think once we hit more of a critical mass on the aformentioned public tools then we'll see opportunities to integrate with API-based CNCF projects (e.g. service meshes)

is your goal to see more open source adoption of this?

Yes. We hope that CNCF can help by being a more vendor-neutral organization than Google, and foster more contributions than we have had in the past.

Some of the contributors mentioned above also feel more comfortable contributing to a CNCF project. So it's also just enabling existing OSS contributions that we want to have.

toumorokoshi commented 1 year ago

In addition to the other reason to join the CNCF: we are actively adjusting the AIPs to clarify API rules that enable low-cost / fully-automated integration with infrastructure-as-code tools, CLIs, and UIs.

So another connection point would be AIPs potential to become the defined standard interface for management of cloud resources.

Happy to discuss or produce any desired docs around this if there's interest.

toumorokoshi commented 1 year ago

Side question: would it be ok to create a Slack channel in the CNCF slack around this project?

We do have a private slack channel but it's not particularly accessible. I know it's early, but we'd love to foster open engagement, and it might be helpful to discuss the sandbox application.

amye commented 1 year ago

Side question: would it be ok to create a Slack channel in the CNCF slack around this project?

We do have a private slack channel but it's not particularly accessible. I know it's early, but we'd love to foster open engagement, and it might be helpful to discuss the sandbox application.

Of course, ping me on Slack if you're having issues.

toumorokoshi commented 1 year ago

Thanks @amye! We are now in the #aip channel in the CNCF slack for those who want to ask questions or learn more about the project.

TheFoxAtWork commented 1 year ago

@AloisReitbauer , @Jenniferstrej , @hongchaodeng - would you all take a look at this project and chime in with any questions or observations?

joshgav commented 1 year ago

@makahmad could you come to the next TAG App Delivery meeting on Wednesday June 21 and present the project to us in about 15 minutes? We'll record it and take notes for TOC and other reviewers.

This project would be one of just a few app development projects in CNCF. Dapr, GRPC, Konveyor and perhaps test frameworks like Microcks (#37) are other examples.

Others have expressed interest in developing microservices patterns and practices, in particular @pasimoes presented this proposal earlier this year: https://github.com/pasimoes/microservices-wg/blob/main/microservices-wg-charter.md.

@pasimoes would you be able to help review this project? Thanks!

pasimoes commented 1 year ago

Hi Josh yes with pleasure. Next Monday I will review it. Thank you.

Paulo Alberto Simoes ∴ | Architect, Cloud Specialist m: +55-21-981-045-770 | @.***

Stay Connected [Linkedin | Twitter | Github | Instagram]: pasimoes

“All our dreams can come true if we have the courage to pursue them.” -- Walt Disney

On 9 Jun 2023, at 8:38 PM, Josh Gavant @.***> wrote:

@makahmad https://github.com/makahmad could you come to the next TAG App Delivery meeting on Wednesday June 21 and present the project to us in about 15 minutes? We'll record it and take notes for TOC and other reviewers.

This project would be one of just a few app development projects in CNCF. Dapr, GRPC and perhaps test frameworks like Microcks (#37 https://github.com/cncf/sandbox/issues/37) are other examples.

Others have expressed interest in developing microservices patterns and practices, in particular @pasimoes https://github.com/pasimoes presented this proposal earlier this year: https://github.com/pasimoes/microservices-wg/blob/main/microservices-wg-charter.md https://github.com/pasimoes/microservices-wg/blob/main/microservices-wg-charter.md.

@pasimoes https://github.com/pasimoes would you be able to help review this project? Thanks!

— Reply to this email directly, view it on GitHub https://github.com/cncf/sandbox/issues/30#issuecomment-1585280660, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADFCVL2BUCWOYI5GZUEQHYLXKOXYVANCNFSM6AAAAAAVUXKG5E. You are receiving this because you were mentioned.

makahmad commented 1 year ago

@joshgav yes I can totally do that. Please include @toumorokoshi as well. How do I get the meeting invite details or will someone email ?

joshgav commented 1 year ago

Hi @makahmad - you can RSVP and get an invite from the TAG community site, here's the June 21 meeting: https://community.cncf.io/e/mzgfad/

Continuous agenda and notes for our meetings are here, agenda for 6/21 is here and already includes AIP :tada:: https://docs.google.com/document/d/1OykvqvhSG4AxEdmDMXilrupsX2n1qCSJUWwTc3I7AOs/edit#heading=h.kgfhy0kww6ym

Talk to you soon!

makahmad commented 1 year ago

Awesome, RSVPed, thank you Josh!

amye commented 1 year ago

/vote-sandbox

git-vote[bot] commented 1 year ago

Vote created

@amye has called for a vote on [Sandbox] API Improvement Proposals (AIP) (#30).

The members of the following teams have binding votes:

Team
@cncf/cncf-toc

Non-binding votes are also appreciated as a sign of support!

How to vote

You can cast your vote by reacting to this comment. The following reactions are supported:

In favor	Against	Abstain
👍	👎	👀

Please note that voting for multiple options is not allowed and those votes won't be counted.

The vote will be open for 7days. It will pass if at least 66% of the users with binding votes vote In favor 👍. Once it's closed, results will be published here as a new comment.

amye commented 1 year ago

/check-vote

git-vote[bot] commented 1 year ago

Vote status

So far 0.00% of the users with binding vote are in favor (passing threshold: 66%).

Summary

In favor	Against	Abstain	Not voted
0	4	0	7

Binding votes (4)

User	Vote	Timestamp
rochaporto	Against	2023-06-13 18:39:01.0 +00:00:00
TheFoxAtWork	Against	2023-06-13 18:05:46.0 +00:00:00
cathyhongzhang	Against	2023-06-13 17:20:49.0 +00:00:00
nikhita	Against	2023-06-14 8:11:16.0 +00:00:00

Non-binding votes (2)

| User | Vote | Timestamp | | ---- | :---: | :-------: | | angellk | In favor | 2023-06-13 16:14:03.0 +00:00:00 | | joshgav | Abstain | 2023-06-14 18:01:58.0 +00:00:00 |

amye commented 1 year ago

/check-vote

git-vote[bot] commented 1 year ago

Vote status

So far 0.00% of the users with binding vote are in favor (passing threshold: 66%).

Summary

In favor	Against	Abstain	Not voted
0	5	1	5

Binding votes (6)

User	Vote	Timestamp
RichiH	Against	2023-06-15 9:27:28.0 +00:00:00
nikhita	Against	2023-06-14 8:11:16.0 +00:00:00
justincormack	Abstain	2023-06-16 10:21:56.0 +00:00:00
cathyhongzhang	Against	2023-06-13 17:20:49.0 +00:00:00
rochaporto	Against	2023-06-13 18:39:01.0 +00:00:00
TheFoxAtWork	Against	2023-06-13 18:05:46.0 +00:00:00

Non-binding votes (2)

| User | Vote | Timestamp | | ---- | :---: | :-------: | | angellk | In favor | 2023-06-13 16:14:03.0 +00:00:00 | | joshgav | Abstain | 2023-06-14 18:01:58.0 +00:00:00 |

git-vote[bot] commented 1 year ago

Vote closed

The vote did not pass.

0.00% of the users with binding vote were in favor (passing threshold: 66%).

Summary

In favor	Against	Abstain	Not voted
0	7	1	3

Binding votes (8)

User	Vote	Timestamp
@TheFoxAtWork	Against	2023-06-13 18:05:46.0 +00:00:00
@nikhita	Against	2023-06-14 8:11:16.0 +00:00:00
@erinaboyd	Against	2023-06-20 13:11:14.0 +00:00:00
@mattfarina	Against	2023-06-16 17:39:38.0 +00:00:00
@rochaporto	Against	2023-06-13 18:39:01.0 +00:00:00
@justincormack	Abstain	2023-06-16 10:21:56.0 +00:00:00
@RichiH	Against	2023-06-15 9:27:28.0 +00:00:00
@cathyhongzhang	Against	2023-06-13 17:20:49.0 +00:00:00

Non-binding votes (2)

| User | Vote | Timestamp | | ---- | :---: | :-------: | | @angellk | In favor | 2023-06-13 16:14:03.0 +00:00:00 | | @joshgav | Abstain | 2023-06-14 18:01:58.0 +00:00:00 |

caniszczyk commented 1 year ago

FYI The Linux Foundation would be interested in hosting this effort in the JDF: https://jointdevelopment.org (where GraphQL, OpenAPI etc live)

@makahmad and other AIP folks, LMK if you want to have that convo

toumorokoshi commented 1 year ago

Wow, thanks @caniszczyk! We'll discuss it in our next meeting (which is a couple weeks out, due to the US holidays).

cncf / sandbox