Introducción a las API de GraphQL en Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

Puede usar API Management para administrar las API de GraphQL: API basadas en el lenguaje de consulta de GraphQL. GraphQL proporciona una descripción completa y comprensible de los datos de una API, lo que proporciona a los clientes la capacidad de recuperar de forma eficaz exactamente los datos que necesitan. Obtener más información sobre GraphQL

API Management le ayuda a importar, administrar, proteger, probar, publicar y supervisar las API de GraphQL. Puede elegir uno de los dos modelos de API:

GraphQL de paso a través Synthetic GraphQL
▪️ API de paso a través al punto de conexión de servicio de GraphQL existente

▪️ Compatibilidad con consultas, mutaciones y suscripciones de GraphQL		 ▪️ API basada en un esquema de GraphQL personalizado

▪️ Compatibilidad con consultas, mutaciones y suscripciones de GraphQL

▪️ Configuración de resoluciones personalizadas, por ejemplo, en orígenes de datos HTTP

▪️ Desarrollo de esquemas de GraphQL y clientes basados en GraphQL mientras se consumen datos de las API heredadas

Disponibilidad

  • Las API de GraphQL se admiten en todos los niveles de servicio de API Management
  • Las API de GraphQL sintéticas no se admiten actualmente en áreas de trabajo de API Management
  • La compatibilidad con suscripciones de GraphQL en las API de GraphQL sintéticas está actualmente en versión preliminar y no está disponible en el nivel consumo

¿Qué es GraphQL?

GraphQL es un lenguaje de consulta estándar del sector de código abierto para las API. A diferencia de las API de estilo REST diseñadas en torno a acciones sobre recursos, las API de GraphQL admiten un conjunto más amplio de casos de uso y se centran en tipos de datos, esquemas y consultas.

La especificación de GraphQL resuelve explícitamente los problemas comunes que experimentan las aplicaciones web cliente que se basan en las API de REST:

  • Puede tomar un gran número de solicitudes para satisfacer las necesidades de datos de una sola página
  • A menudo, las API de REST devuelven más datos de los necesarios para la página que se va a representar
  • La aplicación cliente debe sondear para obtener información nueva

Con API de GraphQL, la aplicación cliente puede especificar los datos que necesitan para representar una página en un documento de consulta que se envía como una única solicitud a un servicio de GraphQL. Una aplicación cliente también puede suscribirse a las actualizaciones de datos insertadas desde el servicio de GraphQL en tiempo real.

Tipos de esquema y operación

En API Management, agregue una API de GraphQL desde un esquema de GraphQL, ya sea recuperado de un punto de conexión de API de GraphQL de back-end o cargado por usted. Un esquema de GraphQL describe:

  • Tipos y campos de objetos de datos que los clientes pueden solicitar desde una API de GraphQL
  • Tipos de operación permitidos en los datos, como consultas

Por ejemplo, un esquema básico de GraphQL para los datos de usuario y una consulta para todos los usuarios podría lucir así:

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

API Management admite los siguientes tipos de operación en los esquemas de GraphQL. Para obtener más información sobre estos tipos de operación, consulte la Especificación de GraphQL.

  • Consulta: captura datos, de forma similar a una operación GETen REST

  • Mutación : modifica los datos del lado servidor, similares a una operación PUT o PATCH en REST

  • Suscripción : habilita la notificación a los clientes suscritos en tiempo real sobre los cambios en los datos del servicio de GraphQL

    Por ejemplo, cuando los datos se modifican a través de una mutación de GraphQL, los clientes suscritos podrían recibir notificaciones automáticas sobre el cambio.

Importante

API Management admite suscripciones implementadas mediante el protocolo WebSocket graphql-ws. No se admiten consultas ni mutaciones en WebSocket.

Resoluciones

Las resoluciones se encargan de asignar el esquema de GraphQL a los datos de back-end, lo que genera los datos de cada campo de un tipo de objeto. El origen de datos podría ser una API, una base de datos u otro servicio. Por ejemplo, una función de resolución sería responsable de devolver datos para la consulta users en el ejemplo anterior.

En API Management, puede crear un solucionador para asignar un campo de un tipo de objeto a un origen de datos back-end. Las resoluciones se configuran para los campos en esquemas sintéticos de API de GraphQL, pero también puede configurarlos para invalidar las resoluciones de campo predeterminadas usadas por las API de GraphQL de paso a través.

API Management actualmente admite solucionadores basados en orígenes de datos de API HTTP, Cosmos DB y Azure SQL para devolver los datos de los campos en un esquema GraphQL. Cada solucionador se configura mediante una directiva personalizada para conectarse al origen de datos y recuperar los datos:

Origen de datos Directiva de solucionador
Origen de datos basado en HTTP (API de REST o SOAP) http-data-source
Base de datos de Cosmos DB cosmosdb-data-source
Azure SQL Database sql-data-source

Por ejemplo, un solucionador basado en la API HTTP de la consulta users anterior podría asignarse a una operación GET en una API de REST de back-end:

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

Para obtener más información sobre cómo configurar un solucionador, consulte Configuración de un solucionador de GraphQL.

Administración de las API de GraphQL

  • Proteger las API de GraphQL mediante la aplicación de directivas de control de acceso existentes y una directiva de validación de GraphQL para protegerse frente a ataques específicos de GraphQL.
  • Explore el esquema de GraphQL y ejecute consultas de prueba en las API de GraphQL en los portales de Azure y para desarrolladores.

Pasos siguientes