Guía de diseño de API

Versión actual de la Guía de diseño de API: 21-02-2017

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 Google 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, incluida la asignación, el registro y la supervisió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 este documento

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.