Tipos de GraphQL

Las consultas son muy similares a las operaciones GET en el sentido de que realizan una búsqueda de solo lectura para obtener datos de su origen. En GraphQL, la Query define todos los puntos de entrada para los clientes que realizan solicitudes a su servidor. Siempre habrá una Query en tu implementación de GraphQL.

Aquí están la Query y los tipos de objetos modificados que hemos utilizado en nuestro ejemplo de esquema anterior:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}
type Occupation {
  title: String
}
type Query {                                   
  people: [Person]
}

Nuestra Query contiene un campo llamado people que devuelve una lista de instancias de Person del origen de datos. Supongamos que necesitamos cambiar el comportamiento de nuestra aplicación y que ahora necesitamos devolver una lista de solo las instancias de Occupation para un propósito diferente. Simplemente podríamos añadirlo a la consulta:

type Query {                                   
  people: [Person]
  occupations: [Occupation]
}

En GraphQL, podemos tratar nuestra consulta como el único origen de las solicitudes. Como puede ver, esto es potencialmente mucho más simple que las implementaciones RESTful, que pueden usar diferentes puntos de conexión para lograr lo mismo (.../api/1/people y .../api/1/occupations).

Suponiendo que tengamos una implementación de resolución para esta consulta, ahora podemos realizar una consulta real. Si bien el tipo de Query existe, debemos llamarlo explícitamente para que se ejecute en el código de la aplicación. Esto se puede hacer con la palabra clave query:

query getItems {
   people {
      name
   }
   occupations {
      title
   }
}

Como puede ver, esta consulta se llama getItems y devuelve people (una lista de objetos de Person) y occupations (una lista de objetos de Occupation). En people, devolvemos solo el campo name de cada Person, mientras que devolvemos el campo title de cada Occupation. La respuesta puede tener un aspecto similar al siguiente:

{
  "data": {
    "people": [
      {
        "name": "John Smith"
      },
      {
        "name": "Andrew Miller"
      },
      .
      .
      .
    ],
    "occupations": [
      {
        "title": "Firefighter"
      },
      {
        "title": "Bookkeeper"
      },
      .
      .
      .
    ]
  }
}

La respuesta de ejemplo muestra cómo los datos siguen la forma de la consulta. Cada entrada recuperada aparece dentro del ámbito del campo. people y occupations devuelven los elementos como listas separadas. Si bien es útil, puede ser más conveniente modificar la consulta para que devuelva una lista con los nombres y las ocupaciones de las personas:

query getItems {
   people {
      name   
      occupation {
        title
      }
}

Se trata de una modificación legal porque nuestro tipo Person contiene un campo occupation de tipo Occupation. Cuando se incluye dentro del ámbito de people, devolvemos el name de cada Person junto con la correspondiente Occupation mediante title. La respuesta puede tener un aspecto similar al siguiente:

}
  "data": {
    "people": [
      {
        "name": "John Smith",
        "occupation": {
          "title": "Firefighter"
        }
      },
      {
        "name": "Andrew Miller",
        "occupation": {
          "title": "Bookkeeper"
        }
      },
      .
      .
      .
    ]
  }
}

Las mutaciones son parecidas a las operaciones que cambian el estado, como PUT o POST. Realizan una operación de escritura para modificar los datos del origen y, a continuación, obtienen la respuesta. Definen los puntos de entrada para las solicitudes de modificación de datos. A diferencia de las consultas, una mutación puede incluirse en el esquema o no según las necesidades del proyecto. Esta es la mutación del ejemplo del esquema:

type Mutation {
  addPerson(id: ID!, name: String, age: Int): Person
}

El campo addPerson representa un punto de entrada que añade una Person al origen de datos. addPerson es el nombre del campo; id, name y age son los parámetros; y Person es el tipo de retorno. Volviendo al tipo de Person:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}

Hemos añadido el campo occupation. Sin embargo, no podemos establecer este campo directamente en Occupation porque los objetos no se pueden transferir como argumentos; son estrictamente tipos de salida. En lugar de ello, deberíamos pasar una entrada con los mismos campos que un argumento:

input occupationInput {
  title: String
}

También podemos actualizar fácilmente nuestro addPerson para incluirlo como parámetro al crear nuevas instancias de Person:

type Mutation {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput): Person
}

Este es el esquema actualizado:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}

type Occupation {
  title: String
}

input occupationInput {
  title: String
}

type Mutation {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput): Person
}

Tenga en cuenta que occupation transferirá el campo title desde occupationInput para completar la creación de la Person objeto en lugar del objeto Occupation original. Suponiendo que tengamos una implementación de resolución para addPerson, ahora podemos realizar una mutación real. Si bien el tipo de Mutation existe, debemos llamarlo explícitamente para que se ejecute en el código de la aplicación. Esto se puede hacer con la palabra clave mutation:

mutation createPerson {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput) {
    name
    age
    occupation {
      title
    }
  }
}

Esta mutación se llama createPerson y addPerson es la operación. Para crear una nueva Person, podemos introducir los argumentos para id, name, age y occupation. En el ámbito de addPerson, también podemos ver otros campos como name, age, etc. Esta es su respuesta; estos son los campos que se devolverán una vez finalizada la operación addPerson. Esta es la parte final del ejemplo:

mutation createPerson {
  addPerson(id: "1", name: "Steve Powers", age: "50", occupation: "Miner") {
    id
    name
    age
    occupation {
      title
    }
  }
}

Si se usa esta mutación, el resultado podría ser parecido a este:

{
  "data": {
    "addPerson": {
      "id": "1",
      "name": "Steve Powers",
      "age": "50",
      "occupation": {
        "title": "Miner"
      }
    }
  }
}

Como puede ver, la respuesta ha devuelto los valores que solicitamos en el mismo formato que se definió en nuestra mutación. Se recomienda devolver todos los valores que se hayan modificado para reducir la confusión y la necesidad de realizar más consultas en el futuro. Las mutaciones permiten incluir varias operaciones dentro de su ámbito. Se ejecutarán secuencialmente en el orden indicado en la mutación. Por ejemplo, si creamos otra operación denominada addOccupation que agregue títulos de trabajo al origen de datos, podemos llamarla así en la mutación después de addPerson. addPerson se gestionará primero y, a continuación, addOccupation.

Las suscripciones utilizan WebSockets para abrir una conexión bidireccional duradera entre el servidor y sus clientes. Normalmente, un cliente se suscribe o escucha al servidor. Siempre que el servidor realice un cambio en el lado del servidor o realice un evento, el cliente suscrito recibirá las actualizaciones. Este tipo de protocolo resulta útil cuando hay varios clientes suscritos y es necesario notificarles los cambios que se produzcan en el servidor o en otros clientes. Por ejemplo, las suscripciones se pueden utilizar para actualizar los feeds de las redes sociales. Puede haber dos usuarios, el usuario A y el usuario B, que estén suscritos a las actualizaciones de notificaciones automáticas cada vez que reciban mensajes directos. El usuario A del cliente A podría enviar un mensaje directo al usuario B del cliente B. El cliente del usuario A enviaría el mensaje directo, que sería procesado por el servidor. A continuación, el servidor enviaría el mensaje directo a la cuenta del usuario B y, al mismo tiempo, enviaría una notificación automática al cliente B.

Este es un ejemplo de Subscription que podríamos añadir al ejemplo del esquema:

type Subscription {                                   
  personAdded: Person
}

El campo personAdded enviará un mensaje a los clientes suscritos cada vez que Person se añada una nueva al nuevo origen de datos. Suponiendo que tengamos una implementación de solucionador para personAdded, ahora podemos usar la suscripción. Si bien el tipo de Subscription existe, debemos llamarlo explícitamente para que se ejecute en el código de la aplicación. Esto se puede hacer con la palabra clave subscription:

subscription personAddedOperation {
  personAdded {
    id
    name
  }
}

La suscripción se llama personAddedOperation y la operación es personAdded. personAdded devolverá los campos id e name de las nuevas instancias de Person. Observando el ejemplo de la mutación, añadimos una operación Person utilizando esta operación:

addPerson(id: "1", name: "Steve Powers", age: "50", occupation: "Miner")

Si nuestros clientes estaban suscritos a las actualizaciones de la Person recién añadida, es posible que vean lo siguiente cuando se ejecute addPerson:

{
  "data": {
    "personAdded": {
      "id": "1",
      "name": "Steve Powers"
    }
  }
}

A continuación se muestra un resumen de lo que ofrecen las suscripciones:

Las suscripciones son canales bidireccionales que permiten al cliente y al servidor recibir actualizaciones rápidas pero constantes. Por lo general, utilizan el protocolo WebSocket, que crea conexiones estandarizadas y seguras.

Las suscripciones son ágiles, ya que reducen la sobrecarga de configuración de la conexión. Una vez suscrito, un cliente puede seguir utilizando esa suscripción durante largos períodos de tiempo. Por lo general, utilizan los recursos informáticos de forma eficiente, ya que permiten a los desarrolladores personalizar la duración de la suscripción y configurar la información que se va a solicitar.

En general, las suscripciones permiten al cliente realizar varias suscripciones a la vez. Al pertenecer a AWS AppSync, las suscripciones solo se utilizan para recibir actualizaciones del servicio de AWS AppSync en tiempo real. No se pueden usar para realizar consultas o mutaciones.

La principal alternativa a las suscripciones es el sondeo, que envía consultas a intervalos establecidos para solicitar datos. Este proceso suele ser menos eficiente que las suscripciones y supone una gran carga tanto para el cliente como para el backend.

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

.
.
.

type Query {                                   
  # code goes here
}
type Mutation {                                   
  # code goes here
}
type Subscription {                                   
  # code goes here
}