rhamiltonsf
commented
4 years ago I've been thinking a lot about this, and have some ideas that don't feel fully fleshed out, but would like to contribute here for brainstorming purposes.
TL;DR I think there is an opportunity here to define a AIP Specification that would result custom AIPs to be comparable to one another and extensible. I propose an example "spec" using the existing AIP definitions. However, I think this is a long term goal, and in the short term we should focus on implementing a hollow AIP implementation that allows adopters to populate with their own AIPs.
I think one of the advantages of AIP adoption across companies would be to enable AIP consumers to take two different AIP implementations and compare them side by side. This would be more easily implemented if the AIP standard defined AIP number/urls/ids for cross cutting concerns across API standards. For example, if I went to google.aip.dev/xyz to read Google's standard for "foo", then I would know that going to acme.aip.dev/xyz is going to contain Acme's standards for "foo".
This would require some level of normalization of the AIPs, as there are a few AIPs that appear to be very specific edge cases for Google.
The rough idea here would be to implement something like the following:
AIP Specification
These AIPs would exist above the currently existing Meta AIPs. They would define an overarching AIP spec that would apply to all AIP implementations. This would define the finalized version of what is being proposed here, specifically under the Guidance section.
Meta AIPs
Similar to the currently implemented AIPs, except less Googley. These would be implementation specific AIPs that define the governance of the AIPs for that organization. A default would be defined for each -- which would also be the actual AIP used by aip.dev -- however it is expected that organizations would fill in a few blanks or amend according to their needs.
Example:
- Guidelines: Defines AIP usage, best practices, extensibility, etc.
- Stakeholders: Defines stakeholders, review policy, how to submit AIPs, etc.
- Workflow: Lists the states of AIPs and their meanings.
- Style Guide
- Contributing
- FAQ
Guidance AIPs
Using the language as it exists today, Guidance AIPs would be the actual implementation of the AIPs and would be where the value resides.
The challenge with standardizing the Guidance APIs is identifying what is a cross cutting concern for API developers, or even cross cutting concerns for those who define the standards.
Below I've taken a stab at categorizing what I think would be the cross cutting concerns that are portrayed in aip.dev. I'm providing this more to attempt to get the point across and am not suggesting that this is the best starting point:
Guidance
- General: AIPs that define the organizations API philosophy rather than rules that can be enforced or validated by a linter.
- Design Philosophy: i.e. Resource oriented design
- Change Management: How to maintain backwards compatibility, deprecation, etc.
- Versioning: May or may not belong in change management?
- API Lifecycle: Replacement for stability levels.
- Documentation
- Bad API Precedent: An interesting existing AIP, that I think is something all AIP implementers are going to need to consider and address.
- Resource:
- Names
- Types
- Caching: Maybe? Attempting to normalize on Freshness Validation and Expiration
- Singleton: May or may not be an edge case.
- Unreachable
- Fields:
- Names
- Types:
- Quantities
- Enumerations
- Time and Duration
- Standardized Codes
- Methods This is an especially interesting section if we consider that AIPs are not specific to one API Protocol.
- Retrieval:
- Single
- Collection
- Update:
- Single
- Collection
- Delete:
- Single
- Collection
- Custom Methods
- Retrieval:
- Messaging:
- Requests: Define format, identification, etc.
- Responses: General format, identification, etc
- Errors
- Pagination
- Partial
Additional Considerations
-
There are likely additional common concerns with each of the bullet points above. For example, some common considerations when defining Field Names are what case to use, what words are reserved, what characters to avoid, etc. These could be part of the AIP specification.
-
Each leaf in the above tree will represent an AIP. However, it seems likely that some organizations may have further addendums to make to a leaf that may result in an additional AIP. For example, if the Google AIPs were redefined in the above approach, would the States AIP be a a leaf of Enumeration? Or a sibling? Or just be defined as a custom header under the Enumeration AIP? The real question to answer regarding such a situation is, which approach would allow custom AIPs (not part of the AIP Specification) be extensible in and of themselves and allow for the greatest comparison between the Spec'ed AIPs in the implementation against those of other implementations.
-
Although these might be standard cross cutting concerns, API definers or AIP implementers may not want to define all of these right away, or ever. And if there is not default implementation of them, they may not want an empty page. There should be a "NA" status that removes the page from the nav bar and search results and displays an NA page if implemented.
-
Here is a list of AIPs that I thought were very specific to Google. These could go in custom categories under any of the above nodes: Transcoding, Long Running Operations, Reading Across Collections, Resource Revisions?, File and Directory Structure, retries for gRPC clients, field behavior documentation, beta blocking changes, Unicode
What I think is working with the above proposal is that it would allow AIPs to be normalized across organizational implementations. I would like to see if it could be normalized across protocols, but I am not entirely convinced that is possible. However there might be additional AIP Specifications specific to the protocol (HTTP vs gRPC) or standard (REST vs RPC) being used.
The Point
All this said, I believe there is an opportunity here to enable side by side comparisons of API standards using a common API definition standard (AIPs). However I don't think the current AIP numbering system would facilitate that. You might be able to say range 150-160 are reserved for Resource definitions, but what happens if a AIP implementor has 20 different custom AIPs they want for Resources. I think a hierarchical approach might be best here, although I like the idea of AIPs (for their name sake) having specific numbers/ids that identify them.
I think there might be an opportunity here to define an AIP specification here that governs how these standards can be defined.
However, all this said, I think the best place to start is with a de-Googled AIP infrastructure that has no AIPs in it and allow adopters to fork and populate their own AIPs using the patterns you have provided.
danbars
dret
Tma38banmarino1
The current thinking is to have a separate GitHub repository that is forkable and can redirect for everything that is not aip-9xxx and serve the 9xxx AIPs directly from the repo