1. The Importance of API Guidelines and Introduction to Google's AIP
API guidelines are valuable because they help engineers design and implement APIs more effectively. However, creating and managing them is not easy. Google addresses this by operating guidelines under the name API Improvement Proposals (AIPs).
2. Characteristics of Google AIP: Flexibility and Continuous Development
The Google guidelines are meant to be guidelines, not rigid requirements. They are very specific to ensure rules are followed. However, they are also flexible to allow for iterations. Google continuously improves the guidelines over time. New versions are released, incorporating input and adding rules for different scenarios. The guidelines themselves have guidelines on how to evolve over time. This ensures they meet the needs of various teams within Google.
- Flexibility - Guidelines are specific but flexible, allowing iterations.
- Continuous Improvement - Guidelines are iterated upon to improve over time.
- Evolution Mechanism - Guidelines include guidelines on how to evolve them.
3. The Importance of Tools for Applying Guidelines
Having guidelines alone is not enough. It is important to build tooling around the guidelines to ensure they work. Guidelines can be very long and detailed, making them hard for humans to read and understand. However, they are easy for machines to implement. An API linter goes hand in hand with the guidelines. It can immediately tell you what is wrong when you write a new API. The guidelines would not be usable without this level of tooling.
4. Starting API Guidelines for Smaller Organizations
For smaller organizations, it is helpful to look at existing resources. The Google AIPs are publicly available. The tooling around them, like the API Linter, is also publicly available. While Google uses Protobuf and gRPC, the idea of how the guidelines are written is useful to examine. It makes sense to start with a small number of guidelines that are relevant to the organization. Building out tooling is crucial. Guidelines without tooling and an enforcement mechanism are unlikely to be useful. Focusing on the tooling around the guidelines is essential for getting started.
- Reference - Look at publicly available resources like Google AIPs.
- Select - Pick a small number of guidelines relevant to the organization.
- Tooling - Build tooling around the selected guidelines.
5. Considerations When Writing Guidelines: Examples and Explanation
When writing guidelines, it is important to provide examples. You should also explain why the guidelines are necessary. It is easier to convince people to follow a guideline when they understand its importance. Explaining why specific guidelines make sense helps to get buy-in from people. This approach makes more sense to people than simply dictating rules. Therefore, you should explain the reasons behind the guidelines. This should be part of the guidelines for guidelines.
6. Additional Resources and References
For those interested in learning more, several resources are available. The Google AIP web page is a good starting point. The API linter is open source and also available. A recent paper titled "API governance at scale" describes how the guidelines work within Google. To understand the theory and necessity behind the guidelines, the book "API Design Patterns" is recommended.
This blog is based on the discussion with Esther Kunden of Google regarding API guidelines and how they are managed at Google, as presented in the source video.