This Changelog highlights notable changes to theAPI Design Guide.

2025-06

• Redirected Design page Naming Convention to Google AIP.

2024-10

• Redirected Design pages to Google AIPs, except for Directory Structureand Naming Conventions.

2021-12

• Changed terminology Networked API to Network API for consistency withhttps://google.aip.dev/9.

2021-09

• Document both Google API error format v1 and v2.

2021-04

• Introduced visibility-based versioning.

• Introduced API title to glossary.

2021-03

• Added annotation for output only fields.

• Update enum value guidance to always include an explicit_UNSPECIFIEDvalue.

• Add guidance on how to generate and parse resource names.

• Addprogress_percent to standard fields.

2021-02

• Added guidance on proto3optional primitive fields.

2021-01

• Updated the Errors page to cover the latest improvement related togoogle.rpc.ErrorInfo andgoogle.api.ErrorReason.

• Added guidance on how to useoauth2l,curl, and System Parametersto troubleshoot errors with Google APIs.

• Added502 error code explanation to the Errors page. It is a networkerror instead of an API error.

2020-12

• Package names should use singlar component names for global consistency.Package names must not use underscores.

2020-09

• Cleaned up some field description requirements; changed some uses of "must"outside RFC 2119 to be RFC 2119 "should" directives.

• Removed thebool deleted standard field, in favor ofgoogle.protobuf.Timestamp delete_time (which was already listed).

2020-07

• Updated documentation.md to match https://google.aip.dev/192#formatting.Markdown tables and raw HTML must not be used in proto comments.

• AddedErrorInfo for error handling.

• Added Large Payloads for design patterns.

2020-04

• Renamed Cloud APIs to Google Cloud APIs in glossary.
• Introduced API and service as synonyms of API service.

2020-02

• Updated versioning to add two versioning strategies (channel-based andrelease-based), remove guidance on point versions, and change how we referto semantic versioning.

2020-01

• Add data retention to design patterns.

2019-11

• Add terminology Cloud APIs to glossary.
• Recommend clients to retry only for UNAVAILABLE errors.

2019-06

• Add "Bool vs Enum vs String" to design patterns.

2019-03

• Add system parameters to standard fields.

2019-02

• Add domain-scoped names to design patterns.

2018-03

• Add streaming half-close semantics to design patterns.

2018-02

• Addread_time to Standard Fields.

2018-01

• Add schema reference for API Service Definition.

2017-12

• Clarify API major version must be the last component of proto package name.

2017-11

• Clarify why theCreate method take an input resource.
• Clarify collection IDs that don't have plural form, such as evidence andweather.
• Add singleton resource to design patterns.
• Clarify C# naming conventions for acronyms and versions.

2017-09

• Addmime_type to standard fields.
• Addexpire_time to standard fields.
• Addstart_time andend_time to standard fields.

2017-02

• Add "API endpoint" to glossary.
• Addupdate_mask to standard fields.
• Add a link toFieldMask to standard methods.
• Mention that OpenAPI spec does not support unsigned integers.
• Clarify that method names should use verbs in the imperative mood.