Skip to content

Stubbing out the aep tooling list #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
toumorokoshi merged 6 commits into from
Jan 11, 2025
Merged

Stubbing out the aep tooling list #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
84f52c5
Stubbing out the aep tooling list
earth2marsh Nov 2, 2024
9c21362
Cleaning up the adoption CTA
earth2marsh Nov 2, 2024
a450a5d
tightening language
earth2marsh Nov 2, 2024
c16594d
Apply suggestions from code review
earth2marsh Nov 8, 2024
fc6d334
Apply suggestions from code review
toumorokoshi Jan 11, 2025
36c6483
updating repo URLs
toumorokoshi Jan 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions config/hero.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
26 changes: 19 additions & 7 deletions pages/general/adopting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
32 changes: 16 additions & 16 deletions pages/general/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.)
Loading