Skip to content
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.

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

feat(AEP-5): add AEP around designing an API #79

Merged
merged 4 commits into from
Mar 6, 2024

Conversation

toumorokoshi
Copy link
Member

@toumorokoshi toumorokoshi commented Jan 21, 2024

To help make the AEPs easier to consume, as well as provide a starting point for those who would like a from-basics starting point on API design, provide a how-to guide.

@toumorokoshi toumorokoshi requested a review from a team as a code owner January 21, 2024 05:01
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Show resolved Hide resolved
aep/general/0005/aep.yaml Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
@rofrankel
Copy link
Collaborator

A few additional thoughts:

  1. Should there be something about common variants of the standard methods, e.g. whether they're long-running?
  2. This is not currently a complete guide. It's definitely a useful description of part of what has to be done, but there are a bunch of other steps too (maybe just protobuf- or OAS-specific stuff). Might be useful to have a section on that, so that someone can easily get from zero to one by following this guide. (I recognize that this goes beyond the scope of API design, but I think it would make it a more useful and complete document for the target audience.)
  3. At Roblox, we have an API design doc template. Should we provide something like that here? It's been really useful for getting design discussions to start off in the right "shape".
  4. A small but complete example API (e.g. @makahmad's Twitter for kids) would be really nice to have here.

To help make the AEPs easier to consumer, as well as provide
a starting point for those who would like a from-basics starting
point on API design, provide a how-to guide.
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
aep/general/0005/aep.md Outdated Show resolved Hide resolved
@rofrankel
Copy link
Collaborator

A few additional thoughts:

  1. Should there be something about common variants of the standard methods, e.g. whether they're long-running?
  2. This is not currently a complete guide. It's definitely a useful description of part of what has to be done, but there are a bunch of other steps too (maybe just protobuf- or OAS-specific stuff). Might be useful to have a section on that, so that someone can easily get from zero to one by following this guide. (I recognize that this goes beyond the scope of API design, but I think it would make it a more useful and complete document for the target audience.)
  3. At Roblox, we have an API design doc template. Should we provide something like that here? It's been really useful for getting design discussions to start off in the right "shape".
  4. A small but complete example API (e.g. @makahmad's Twitter for kids) would be really nice to have here.

Filed #96 to capture this.

@toumorokoshi toumorokoshi merged commit 9a8f676 into aep-dev:main Mar 6, 2024
2 checks passed
@toumorokoshi
Copy link
Member Author

I forced-merge this due to some of the comments being on commits that no longer exist due to force-push.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants