This Changelog highlights notable changes to the API Design Guide.
- Changed terminology Networked API to Network API for consistency with https://google.aip.dev/9.
- Document both Google API error format v1 and v2.
Introduced visibility-based versioning.
Introduced API title to glossary.
Added annotation for output only fields.
Update enum value guidance to always include an explicit
Add guidance on how to generate and parse resource names.
progress_percentto standard fields.
- Added guidance on proto3
Updated the Errors page to cover the latest improvement related to
Added guidance on how to use
curl, and System Parameters to troubleshoot errors with Google APIs.
502error code explanation to the Errors page. It is a network error instead of an API error.
- Package names should use singlar component names for global consistency. Package names must not use underscores.
Cleaned up some field description requirements; changed some uses of "must" outside RFC 2119 to be RFC 2119 "should" directives.
bool deletedstandard field, in favor of
google.protobuf.Timestamp delete_time(which was already listed).
Updated documentation.md to match https://google.aip.dev/192#formatting. Markdown tables and raw HTML must not be used in proto comments.
ErrorInfofor error handling.
Added Large Payloads for design patterns.
- Renamed Cloud APIs to Google Cloud APIs in glossary.
- Introduced API and service as synonyms of API service.
- Updated versioning to add two versioning strategies (channel-based and release-based), remove guidance on point versions, and change how we refer to semantic versioning.
- Add data retention to design patterns.
- Add terminology Cloud APIs to glossary.
- Recommend clients to retry only for UNAVAILBLE errors.
- Add "Bool vs Enum vs String" to design patterns.
- Add system parameters to standard fields.
- Add domain-scoped names to design patterns.
- Add streaming half-close semantics to design patterns.
read_timeto Standard Fields.
- Add schema reference for API Service Definition.
- Clarify API major version must be the last component of proto package name.
- Clarify why the
Createmethod take an input resource.
- Clarify collection IDs that don't have plural form, such as evidence and weather.
- Add singleton resource to design patterns.
- Clarify C# naming conventions for acronyms and versions.
mime_typeto standard fields.
expire_timeto standard fields.
end_timeto standard fields.
- Add "API endpoint" to glossary.
update_maskto standard fields.
- Add a link to
FieldMaskto standard methods.
- Mention that OpenAPI spec does not support unsigned integers.
- Clarify that method names should use verbs in the imperative mood.