Configura Endpoints

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:

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:

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

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 dominios cloud.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 que YOUR_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 que YOUR_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?