Introducción
Esta es una guía de diseño general para APIs conectadas en red. Se ha usado en Google desde el 2014 y es la guía que sigue Google al diseñar APIs de Cloud y otras APIs de Google. Esta guía de diseño se comparte aquí para informar a los desarrolladores externos y para que nos resulte más fácil trabajar juntos.
Los desarrolladores de Cloud Endpoints pueden encontrar esta guía especialmente útil al diseñar APIs gRPC, y les recomendamos encarecidamente que utilicen estos principios de diseño. Sin embargo, no es obligatorio usarlo. Puedes usar Cloud Endpoints y gRPC sin seguir la guía.
Esta guía se aplica tanto a las APIs REST como a las APIs RPC, y se centra específicamente en las APIs gRPC. Las APIs gRPC usan Protocol Buffers para definir su superficie de API y API Service Configuration para configurar sus servicios de API, como la asignación HTTP, el registro y la monitorización. Las APIs de Google y las APIs gRPC de Cloud Endpoints usan las funciones de asignación HTTP para la transcodificación de JSON/HTTP a Protocol Buffers/RPC.
Esta guía es un documento dinámico que se irá actualizando a medida que se adopten y aprueben nuevos estilos y patrones de diseño. Por eso, nunca estará completa y siempre habrá espacio para el arte y la artesanía del diseño de APIs.
Convenciones usadas en esta guía
Las palabras clave de nivel de requisito "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" y "OPTIONAL" que se usan en este documento se deben interpretar tal como se describe en el 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 cómo implementar un diseño orientado a recursos para las APIs RPC y 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 las siguientes APIs:
- 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, consulte sus AIPs relacionados.
- Para los campos estándar, consulta AIP-148.
- Para ver los errores, consulta AIP-193.
- Para ver patrones de diseño, consulta la guía de AIP sobre patrones de diseño.
- Para obtener información sobre la documentación de la API insertada, consulta AIP-192.
- Para obtener información sobre cómo usar proto3, consulta la sección Sintaxis de AIP-191.
- Para obtener información sobre la gestión de versiones, consulta AIP-185.
- Para obtener información sobre la retrocompatibilidad, consulta AIP-180.
- Para obtener información sobre la estructura de los archivos, consulta la sección Diseño de los archivos de AIP-191.
- Para consultar un glosario de términos, consulta AIP-9.
- Para consultar las convenciones de nomenclatura, consulta AIP-190.
Para obtener información sobre los siguientes temas, consulta las páginas relacionadas de esta guía.