diff --git a/config/hero.yaml b/config/hero.yaml index 36d52444..f2a2a73e 100644 --- a/config/hero.yaml +++ b/config/hero.yaml @@ -7,9 +7,7 @@ buttons: shortcuts: - title: Curious about the basics? description: | - AEPs are a combination of design guidance and a system we use to manage - and track that guidance. Learn more about how the AEP program works in - the first AEP! + AEPs are a collection of API design specifications, design patterns, and guidance. In addition, the AEP project includes tools to help produce AEP-compliant APIs, as well a clients (command-lines, UIs, Declarative plugins) that consume them. Learn more about how the AEP program works in the first AEP! button: href: /1 text: Read AEP-1 @@ -21,10 +19,10 @@ shortcuts: button: href: /contributing text: Contribute to the project - - title: Want to use AEPs for your organization? + - title: Want to adopt AEPs in your organization? description: | - AEPs are designed to be useful outside of Google. Take a look at how you - might choose which AEPs are best suited to your API design needs. + AEPs were adapted from [Google's AIP project](https://google.aip.dev/), but also enhanced with improved + guidance for APIs, tooling to generate and validate them, and clients to interact with them. The result is better designed and consumable APIs. button: href: /adopting text: Learn more diff --git a/pages/general/adopting.md b/pages/general/adopting.md index 0dcf7154..ccb55622 100644 --- a/pages/general/adopting.md +++ b/pages/general/adopting.md @@ -1,11 +1,23 @@ # Adopting AEPs for your company -Currently, we encourage adoption of AEPs via having your APIs adhere to the -guidance served at https://aep.dev. +By adopting the guidelines from the API Enhancement Proposals, you establish a +much tighter and efficient possibility space. APIs that follow the +[AEP guidance](https://aep.dev) from the design stage: -In the future, we plan to introduce a broader ecosystem of tooling including: +- are more consistent within and across teams, reducing cognitive load for API + consumers +- reduce arguments about API design decisions, thanks to the AEP specification, + tools, and exemplar design patterns -- A forkable repository which allows for internal mirrors and - organization-specific guidance. -- Client-side and server-side code generators. -- Validators to ensure adherence to the specification. +Having an AEP-compliant API also means benefitting from the AEP ecosystem of +tooling, such as: + +- Linters and validators to ensure adherence to the AEP design specification + ([proto](https://github.com/aep-dev/api-linter)/[openapi](https://github.com/aep-dev/aep-openapi-linter)) +- A dynamic command line interface generator that make it easier to work with + APIs ([aepcli](https://github.com/aep-dev/aepcli)) +- Client-side and server-side code generators + ([aepc](https://github.com/aep-dev/aepc)) +- ... and more! Please start a + [discussion](https://github.com/aep-dev/aep.dev/discussions) if there is + something you wish to see, validate, or prioritize. diff --git a/pages/general/faq.md b/pages/general/faq.md index 207e23d5..5af328c1 100644 --- a/pages/general/faq.md +++ b/pages/general/faq.md @@ -1,22 +1,22 @@ # Frequently Asked Questions -## What is the difference between aep.dev and google.aip.dev? +## What are the differences between AEPs and AIPs? -As aep.dev is derived from [google.aip.dev](https://google.aip.dev), a lot of -content will be familiar. +If you are familiar with Google's API Improvement Proposals +[google.aip.dev](https://google.aip.dev), then much of the +[API Enhancement Proposals](https://aep.dev) content will be familiar. -However, aep.dev has significant philosophical differences: +However, AEPs have notable philosophical differences, including: -- aep.dev prioritizes broadly applicable design guidance, while google.aip.dev - prioritizes design guidance this best for Google, such as guidance that is - backwards-compatible with existing decisions at the company. -- aep.dev is protocol-agonistic, and considers gRPC and HTTP + JSON as - first-class protocols for which examples and other content will be authored. -- google.aip.dev encourages forking the guidance, while aep.dev focuses on a - set of core specification that should not be forked, paired with a method to - add organization-specific guidance that does not contradict the - specification. +- AEPs prioritize broadly applicable design guidance for any company, while + AIPs prioritized design guidance specifically for Google (e.g., providing + backwards-compatibility with prior decisions to meet Google-specific needs). +- AEPs are protocol-agonistic and consider both gRPC and HTTP+JSON as + first-class protocols for which examples and other content are necessary. +- AEPs focuses on a core specification that is not intended to be forked, + paired with a mechanism for optional organization-specific guidance to extend + the specification. AIPs encourage forking its guidance outright. -aep.dev also has the advantage of hindsight, which makes it possible in some -cases to provide better guidance than google.aip.dev. (One small example: -renaming `page_size` to `max_page_size` for requests to paginated API methods.) +AEPs also have the advantage of hindsight, which makes it possible in some +cases to provide better guidance. (One small example: renaming `page_size` to +`max_page_size` for requests to paginated API methods.)