Cloud Endpoints es compatible con las API descritas si se usa la versión 2.0 de la especificación de OpenAPI. Debes describir la superficie de la API y configurar características de Endpoints como reglas de autenticación o cuotas en un documento de OpenAPI.
Endpoints hace un uso especial de los siguientes campos requeridos en tu documento de OpenAPI:
host
info.title
info.version
operationId
En esta página, se proporciona información sobre la forma en la que Endpoints usa los campos anteriores. Con esta información, puedes terminar de preparar tu documento de OpenAPI para su implementación.
Requisitos previos
Como punto de partida, en esta página se supone que ya:
- Un proyecto de Google Cloud
- Conocimientos básicos de OpenAPI.
- Un documento de OpenAPI en el formato descrito en el Estructura básica de Swagger en la documentación de Google Cloud.
host
Cloud Endpoints usa el nombre que configuras en el campo host
de tu documento de OpenAPI como el nombre de tu servicio.El nombre de tu servicio de API debe ser único en Google Cloud. Dado que Endpoints usa nombres compatibles con DNS para identificar los servicios, te recomendamos que uses el nombre de dominio o de subdominio de tu API como el nombre del servicio. Según este enfoque, el nombre del servicio que aparece en la página Endpoints Services coincide con el nombre que se usa en las solicitudes para tu API. Además, si el nombre de tu servicio y tu nombre de dominio son iguales, puedes crear un Portal de Cloud Endpoints para tus usuarios de API. Endpoints tiene los siguientes requisitos para el nombre del servicio:
- La longitud máxima del nombre de dominio es de 253 caracteres.
- El nombre de dominio debe comenzar con una letra minúscula.
- Cada sección del nombre de dominio, que está delimitada por puntos, tiene los requisitos siguientes:
- Debe comenzar con una letra en minúscula.
- No debe terminar con un guion.
- Los caracteres restantes pueden ser letras minúsculas, números o guiones.
- La longitud máxima es de 63 caracteres.
Puedes registrar tu propio dominio personalizado (como example.com
) o puedes usar un dominio administrado por Google.
Usar un dominio administrado por Google
En Google, se aloja la propiedad de los dominioscloud.goog
y appspot.com
y se los administra.
Si deseas usar un dominio administrado en Google, debes usar tu ID del proyecto de Google Cloud como parte del nombre del servicio. Dado que los proyectos de Google Cloud tienen un ID del proyecto global único, con este requisito, se garantiza que el nombre del servicio sea único.
El nombre de dominio que uses depende del backend que se alojará en tu API con las siguientes características:
Para las API que se alojan en el entorno flexible de App Engine, debes usar el dominio
appspot.com
, y el nombre del servicio debe estar en el siguiente formato, en el queYOUR_PROJECT_ID
es tu ID del proyecto de Google Cloud:YOUR_PROJECT_ID.appspot.com
Cuando implementas tu API en App Engine, se crea una entrada DNS de forma automática con un nombre en el formato
YOUR_PROJECT_ID.appspot.com
.Para las API que se alojarán en Compute Engine, Google Kubernetes Engine o Kubernetes, debes usar el dominio
cloud.goog
y el nombre del servicio debe estar en el siguiente formato, en el queYOUR_API_NAME
es el nombre de tu API:YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
Para usar este dominio como el nombre de dominio de la API, consulta Configurar DNS en el dominio
cloud.goog
.
Usa un dominio personalizado
Si no quieres usar un dominio administrado por Google, puedes usar un dominio personalizado (por ejemplo, myapi.mycompany.com
) para el cual tengas autorización.
Antes de implementar la configuración de tu API, sigue los pasos que aparecen en Verificar la propiedad para el dominio.
info.title
En el campo info.title
se incluye un nombre fácil de usar para tu API. En la página Endpoints > Services de la consola de Google Cloud, se muestra el texto que configuras en el campo info.title
. Si tienes más de una API por proyecto de Google Cloud, el nombre de la API se muestra en una lista cuando abres la página por primera vez. Puedes hacer clic en el nombre de la API para abrir otra página que muestre las métricas, el historial de implementaciones y más información sobre la API.
info.version
En la página Endpoints > Services de la consola de Google Cloud, se muestra el número de versión de tu API. Antes de implementar la configuración de tu API por primera vez, te recomendamos que:
Configura el número de versión en el campo
info.version
de la versión de la API aplicable, por ejemplo,1.0
.Configura el campo
basePath
en el número de la versión principal, por ejemplo,/v1
.
Para obtener información sobre el control de versiones de tu API, consulta Administración del ciclo de vida de las API.
operationId
Aunque operationId
es un campo opcional en la Especificación de OpenAPI, Endpoints solicita este número, dado que se usa para la identificación interna de la operación. La string que usas para operationId
debe ser única dentro de tu API. Consulta la descripción de
operationId
en la Especificación de OpenAPI para obtener orientación sobre la asignación de nombres.
¿Qué sigue?
- Implementar la configuración de Endpoints
- Implementa el backend de la API
- Configura la autenticación