Introducción a GraphQL en Azure

En este artículo, aprenderá los conceptos básicos de GraphQL API.

GraphQL API da al cliente el control de los resultados de la API.

GraphQL proporciona un lenguaje de consulta que permite solicitar datos de un servidor de forma declarativa. Puede solicitar lo siguiente:

  • Los datos específicos que necesita en el esquema en que los necesita. Que los cambios en el esquema de datos los realice el cliente en la definición de esquema de la API.
  • Que se devuelvan los datos en un esquema anidado que represente una colección de objetos, con independencia del número de orígenes de datos necesarios. Compare esta API con una API REST clásica que necesita varias solicitudes de API para proporcionar los mismos datos.

GraphQL actúa como una capa entre el punto de conexión de API y la base de datos. Los proveedores de GraphQL, como Apollo, proporcionan gran parte de la funcionalidad que necesita para compilar las API de GraphQL. Al igual que la mayoría del software que usa bases de datos, el proveedor no puede escribir las consultas de base de datos reales por usted, porque solo usted conoce los datos. Los proveedores suelen generar gran parte del código reutilizable para usar GraphQL, por lo que a usted solo se le deja la lógica empresarial o de middleware.

Su primera consulta de GraphQL API de Apollo

Una consulta de GraphQL, que solicita el valor hello al servidor, se parece a JSON, pero no es un objeto JSON verdadero:

{
    hello
}

El servidor responde con JSON:

{
    "hello":"Hello from GraphQL backend"
}

Lectura y escritura de Apollo GraphQL con consultas y mutaciones

En GraphQL, se realizan operaciones de lectura en los datos mediante consultas y operaciones de escritura, como inserciones y actualizaciones, usando para ello mutaciones.

Obtención de todos los elementos con una consulta de GraphQL API de Apollo

Supongamos que tiene un origen de datos que contiene mensajes con un identificador, un autor y el contenido de cada mensaje.

Para consultar todos los mensajes, la consulta de GraphQL sería así:

{
  getMessages {
    id
    content
    author
  }
}

El punto de conexión de API podría ser así: /api/graphql y la solicitud cURL podría ser así:

curl -X POST 'http://localhost:7071/api/graphql' \
     -H 'content-type: application/json' \
     --data-raw '{"query":"{ getMessages { id content author } }"}'

La respuesta de la API sería así:

{
    "data": {
        "getMessages": [
            {
                "id": "d8732ed5-26d8-4975-98a5-8923e320a77f",
                "author": "dina",
                "content": "good morning"
            },
            {
                "id": "33febdf6-e618-4884-ae4d-90827280d2b2",
                "author": "john",
                "content": "oh happy day"
            }
        ]
    }
}

Devolución de un subconjunto de los datos con la consulta de cliente

Aunque en el ejemplo anterior se devolvieron todos los mensajes y todos los campos de un mensaje, puede haber ocasiones en las que el cliente solo quiera determinados campos. Para esto no hace falta código nuevo para la API, pero sí una nueva consulta del cliente que describa el esquema de la respuesta esperada.

Esta es una consulta que obtiene todos los mensajes, pero solo los campos id y author de ellos. La consulta indica al servidor de GraphQL que no envíe los valores de content al cliente:

{
  getMessages {
    id
    author
  }
}

El punto de conexión de API podría ser así: /api/graphql y la solicitud cURL podría ser así:

curl -X POST 'http://localhost:7071/api/graphql' \
     -H 'content-type: application/json' \
     --data-raw '{"query":"{ getMessages { id author } }"}'

La respuesta de la API sería así:

{
    "data": {
        "getMessages": [
            {
                "id": "d8732ed5-26d8-4975-98a5-8923e320a77f",
                "author": "dina"
            },
            {
                "id": "33febdf6-e618-4884-ae4d-90827280d2b2",
                "author": "john"
            }
        ]
    }
}

Cambio de los datos con una mutación

Para cambiar los datos, use una mutación que indique el cambio y también defina los datos que se devolverán con él. Supongamos que tiene un origen de datos que contiene mensajes con un identificador, un autor y el contenido de cada mensaje y quiere agregar un nuevo mensaje.

Sintaxis de GraphQL de Apollo

Para agregar un nuevo mensaje, la mutación de GraphQL sería así:

mutation {
  createMessage(input: { author: "John Doe", content: "Oh happy day" }) {
    id
  }
}

Observe que la última sección entre llaves, { id }, describe el esquema que el cliente quiere en la respuesta.

Solicitud cURL HTTP

El punto de conexión de API podría ser así: /api/graphql y la solicitud cURL podría ser así:

curl 'http://localhost:7071/api/graphql' \
    -X POST \
    -H 'Content-Type: application/json' \
    --data-raw '{"query": "mutation{ createMessage(input: { author: \"John Doe\", content: \"Oh happy day\" }){ id } }"}'

Respuesta HTTP

La respuesta de la API sería así:

{
    "data": {
        "createMessage": {
            "id":"7f1413ec-4ffa-45bc-bce2-583072745d84"
        }
    }
}

Cambio de los datos con variables para una mutación de Apollo

La consulta anterior codificaba de forma rígida los valores de author y content. Este método no se recomienda, pero se usa aquí para ilustrar dónde se esperan los valores en la solicitud. Ahora, puede cambiar la misma solicitud de mutación para permitir variables y que el cliente que realiza la solicitud pueda insertar los valores adecuados.

Cuerpo de la solicitud cURL HTTP

Para pasar variables, envíelas en la propiedad variables. Descríbalos en los parámetros de mutación con $ y un tipo que coincida con lo que espera la mutación, como String!. A continuación, asígnelos a los argumentos de mutación según sea necesario.

{
  "variables": { "author": "jimbob", "content": "sunny in the `ham" },
  "query": "mutation ($author: String!, $content: String!) { createMessage(input: { author: $author, content: $content }){ id }}"
}

Solicitud cURL

El siguiente cuerpo de solicitud, el valor --data-raw, se quita de todo el formato.

curl 'http://localhost:7071/api/graphql' \
    -X POST \
    -H 'Content-Type: application/json' \
    --data-raw '{"variables": { "author": "jimbob", "content": "sunny in the `ham" },"query": "mutation ($author: String!, $content: String!){ createMessage(input: { author: $author, content: $content }){ id } }"}'

Pasos siguientes