Introducción
Esta es una guía de diseño general para las API conectadas en red. Se usa en Google desde 2014 y es la guía que sigue Google cuando diseña las API de Cloud y otras API de Google. Esta guía de diseño se comparte aquí a fin de informar a los desarrolladores externos y para facilitar a todos el trabajo en conjunto.
Puede que esta guía sea útil, en particular, para los desarrolladores de Cloud Endpoints al momento de diseñar las API de gRPC. Recomendamos a los desarrolladores usar estos principios fundamentales de diseño. Sin embargo, no exigimos su uso. Puedes usar Cloud Endpoints y gRPC sin seguir la guía.
Esta guía se aplica a las API de REST y a las API de RPC, con un enfoque particular en las API de gRPC. Estas usan búferes de protocolo a fin de definir su superficie de API y la configuración de los servicios de la API para configurar los servicios de las API, incluido el registro, la supervisión y la asignación HTTP. Las API de Google y las API de gRPC de Cloud Endpoints usan las características de asignación HTTP para JSON y HTTP a la transcodificación de los búferes de protocolo y RPC.
Esta guía es un documento dinámico y se realizarán incorporaciones con el tiempo a medida que se adopten y aprueben estilos nuevos y patrones de diseño. De esta forma, nunca estará completa en su totalidad y siempre habrá un amplio margen para el arte y las manualidades a la hora de diseñar la API.
Convenciones que se usan en esta guía
Las palabras clave de nivel requerido “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, y “OPTIONAL” que se usan en el documento se deben interpretar cómo se describe en RFC 2119.
En este documento, estas palabras clave se resaltan con la fuente negrita.
Secciones
Diseño orientado a recursos
Para obtener información sobre la implementación de un diseño orientado a los recursos para RPC y APIs de REST, consulta AIP-121.
Nombres de recursos
Para obtener información sobre los nombres de recursos, consulta AIP-122.
Métodos estándar
Para obtener información general sobre los métodos, consulta AIP-130.
Para obtener información sobre los métodos estándar, consulta los siguientes AIP:
- Para
Get, consulta AIP-131. - Para
List, consulta AIP-132. - Para
Create, consulta AIP-133. - Para
Update, consulta AIP-134. - Para
Delete, consulta AIP-135.
Métodos personalizados
Para obtener información sobre los métodos personalizados, consulta AIP-136.
Temas adicionales
Para obtener información sobre los siguientes temas, consulta sus AIPs relacionados.
- Para los campos estándar, consulta AIP-148.
- Para ver los errores, consulta AIP-193.
- Para obtener información sobre los patrones de diseño, consulta la orientación de AIP sobre los patrones de diseño.
- Para obtener información sobre la documentación de la API intercalada, consulta AIP-192.
- Para usar proto3, consulta la sección de sintaxis de AIP-191.
- Para el control de versiones, consulta AIP-185.
- Para obtener información sobre la retrocompatibilidad, consulta AIP-180.
- Para obtener información sobre la estructura de archivos, consulta la sección Diseño de archivos del AIP-191.
- Para obtener un Glosario de términos, consulta el AIP-9.
Para obtener información sobre los siguientes temas, consulta sus páginas relacionadas en esta guía.