Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Neste registro de alterações, você verá as mudanças relevantes no Guia de design da API.
2025-06
Redirecionamos a convenção de nomenclatura da página de design para a AIP do Google.
2024-10
Redirecionamos as páginas de design para as APIs do Google, exceto Estrutura de diretórios e Convenções de nomenclatura.
2021-12
Mudança da terminologia "API em rede" para "API de rede" para consistência com
https://google.aip.dev/9.
2021-09
Documentação dos formatos de erro da API do Google v1 e v2.
2021-04
Lançamento do controle de versão baseado em visibilidade.
Inclusão do título da API ao glossário.
2021-03
Adição de anotação apenas a campos de saída.
Atualização da orientação do valor de enumeração para sempre incluir um valor _UNSPECIFIED
explícito.
Adição de orientações sobre como gerar e analisar nomes de recursos.
Adicione progress_percent aos campos padrão.
2021-02
Adição de orientações sobre os campos primitivos do proto3 optional.
2021-01
Atualização da página de erros para incluir as melhorias mais recentes relacionadas a
google.rpc.ErrorInfo e google.api.ErrorReason.
Inclusão de orientações sobre como usar os parâmetros oauth2l, curl e do sistema
para resolver erros com as APIs do Google.
Adição de uma explicação sobre o código de erro 502 à página "Erros". Trata-se de um erro
de rede em vez de um erro de API.
2020-12
Nomes de pacotes devem usar nomes de componentes no singular para consistência global.
Os nomes dos pacotes não podem usar sublinhados.
2020-09
Alguns requisitos de descrição do campo foram limpos. Foram alterados alguns usos de "obrigatório" fora do RFC 2119 para serem diretivas "necessárias" do RFC 2119.
O campo padrão bool deleted foi removido em favor do google.protobuf.Timestamp delete_time (que já estava listado).
2020-07
Updated documentation.md to match https://google.aip.dev/192#formatting.
As tabelas Markdown e HTML bruto não podem ser usadas em comentários de proto.
Adição de ErrorInfo para tratamento de erros.
Adição de grandes payloads para padrões de projetos.
2020-04
Renomeação de APIs do Cloud para APIs do Google Cloud no glossário.
Introdução da API e do serviço como sinônimos do serviço da API.
2020-02
Atualização do controle de versão para adicionar duas estratégias de controle de versão (com base no canal e na versão), remover orientações sobre versões de pontos e alterar a forma como nos referimos ao controle de versão semântico.
2020-01
Adição da retenção de dados aos padrões de design.
2019-11
Adição da terminologia das APIs do Cloud ao glossário.
Recomendação para que os clientes tentem novamente somente para erros UNAVAILABLE.
2019-06
Adicione "Bool x Enum x String" aos padrões de design.
2019-03
Adiciona parâmetros do sistema aos campos padrão.
2019-02
Adiciona nomes com escopo de domínio para criar padrões.
2018-03
Adiciona a semântica de fechamento de streaming aos padrões de design.
2018-02
Adicione read_time aos campos padrão.
2018-01
Adiciona referência de esquema à definição do serviço da API.
2017-12
Esclarece que a versão principal da API precisa ser o último componente do nome do pacote proto.
2017-11
Esclareça por que o método Create usa um recurso de entrada.
Explica códigos de coleção que não têm forma plural, como evidência e clima.
Adiciona o recurso singleton aos padrões de design.
Esclarece convenções de nomenclatura C# para siglas e versões.
2017-09
Adicione mime_type aos campos padrão.
Adicione expire_time aos campos padrão.
Adicione start_time e end_time aos campos padrão.
2017-02
Adiciona "ponto de extremidade da API" ao glossário.
Adicione update_mask aos campos padrão.
Adicione um link para FieldMask aos métodos padrão.
Menciona que as especificações do OpenAPI não aceitam números inteiros sem assinatura.
Esclarece que os nomes dos métodos precisam usar verbos no modo imperativo.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[[["\u003cp\u003eThis changelog documents updates to the API Design Guide, including changes to terminology, error handling, and field requirements.\u003c/p\u003e\n"],["\u003cp\u003eRecent changes include redirecting certain design pages to Google AIPs and updating terminology to align with Google API standards.\u003c/p\u003e\n"],["\u003cp\u003eThe guide has undergone modifications to field descriptions, versioning strategies, and the inclusion of standard fields like \u003ccode\u003eread_time\u003c/code\u003e, \u003ccode\u003emime_type\u003c/code\u003e, \u003ccode\u003eexpire_time\u003c/code\u003e, \u003ccode\u003estart_time\u003c/code\u003e, and \u003ccode\u003eend_time\u003c/code\u003e over time.\u003c/p\u003e\n"],["\u003cp\u003eError handling has been improved with updates to \u003ccode\u003egoogle.rpc.ErrorInfo\u003c/code\u003e and \u003ccode\u003egoogle.api.ErrorReason\u003c/code\u003e, along with guidance on troubleshooting errors and the addition of \u003ccode\u003eErrorInfo\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eDesign patterns have been added and enhanced, with examples such as streaming half-close semantics, singleton resources, data retention, and guidance on bool vs enum vs string.\u003c/p\u003e\n"]]],[],null,["# Changelog\n\nThis Changelog highlights notable changes to the\n[API Design Guide](/apis/design).\n\n2025-06\n-------\n\n- Redirected Design page Naming Convention to Google AIP.\n\n2024-10\n-------\n\n- Redirected Design pages to Google AIPs, except for Directory Structure and Naming Conventions.\n\n2021-12\n-------\n\n- Changed terminology Networked API to Network API for consistency with https://google.aip.dev/9.\n\n2021-09\n-------\n\n- Document both Google API error format v1 and v2.\n\n2021-04\n-------\n\n- Introduced visibility-based versioning.\n\n- Introduced API title to glossary.\n\n2021-03\n-------\n\n- Added annotation for output only fields.\n\n- Update enum value guidance to always include an explicit `_UNSPECIFIED`\n value.\n\n- Add guidance on how to generate and parse resource names.\n\n- Add `progress_percent` to standard fields.\n\n2021-02\n-------\n\n- Added guidance on proto3 `optional` primitive fields.\n\n2021-01\n-------\n\n- Updated the Errors page to cover the latest improvement related to\n `google.rpc.ErrorInfo` and `google.api.ErrorReason`.\n\n- Added guidance on how to use `oauth2l`, `curl`, and System Parameters\n to troubleshoot errors with Google APIs.\n\n- Added `502` error code explanation to the Errors page. It is a network\n error instead of an API error.\n\n2020-12\n-------\n\n- Package names should use singlar component names for global consistency. Package names must not use underscores.\n\n2020-09\n-------\n\n- Cleaned up some field description requirements; changed some uses of \"must\"\n outside RFC 2119 to be RFC 2119 \"should\" directives.\n\n- Removed the `bool deleted` standard field, in favor of\n `google.protobuf.Timestamp delete_time` (which was already listed).\n\n2020-07\n-------\n\n- Updated documentation.md to match https://google.aip.dev/192#formatting.\n Markdown tables and raw HTML must not be used in proto comments.\n\n- Added `ErrorInfo` for error handling.\n\n- Added Large Payloads for design patterns.\n\n2020-04\n-------\n\n- Renamed Cloud APIs to Google Cloud APIs in glossary.\n- Introduced API and service as synonyms of API service.\n\n2020-02\n-------\n\n- 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.\n\n2020-01\n-------\n\n- Add data retention to design patterns.\n\n2019-11\n-------\n\n- Add terminology Cloud APIs to glossary.\n- Recommend clients to retry only for UNAVAILABLE errors.\n\n2019-06\n-------\n\n- Add \"Bool vs Enum vs String\" to design patterns.\n\n2019-03\n-------\n\n- Add system parameters to standard fields.\n\n2019-02\n-------\n\n- Add domain-scoped names to design patterns.\n\n2018-03\n-------\n\n- Add streaming half-close semantics to design patterns.\n\n2018-02\n-------\n\n- Add `read_time` to Standard Fields.\n\n2018-01\n-------\n\n- Add schema reference for API Service Definition.\n\n2017-12\n-------\n\n- Clarify API major version must be the last component of proto package name.\n\n2017-11\n-------\n\n- Clarify why the `Create` method take an input resource.\n- Clarify collection IDs that don't have plural form, such as evidence and weather.\n- Add singleton resource to design patterns.\n- Clarify C# naming conventions for acronyms and versions.\n\n2017-09\n-------\n\n- Add `mime_type` to standard fields.\n- Add `expire_time` to standard fields.\n- Add `start_time` and `end_time` to standard fields.\n\n2017-02\n-------\n\n- Add \"API endpoint\" to glossary.\n- Add `update_mask` to standard fields.\n- Add a link to `FieldMask` to standard methods.\n- Mention that OpenAPI spec does not support unsigned integers.\n- Clarify that method names should use verbs in the imperative mood."]]
