Guía de diseño de APIs

Registro de cambios

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

Siguiente
Diseño orientado a recursos