Comenzar a crear API GraphQL con Node

Todos tenemos una serie de intereses y pasiones. Por ejemplo, me interesa JavaScript, el indie rock y el hip hop de los 90, el jazz oscuro, la ciudad de Pittsburgh, la pizza, el café y las películas protagonizadas por John Lurie. También tenemos familiares, amigos, conocidos, compañeros de clase y colegas que también tienen sus propias relaciones sociales, intereses y pasiones. Algunas de estas relaciones e intereses se superponen, como mi amigo Riley, que comparte mi interés por el hip hop y la pizza de los 90. Otros no, como mi colega Harrison, que prefiere Python a JavaScript, solo bebe té y prefiere la música. pop real. En conjunto, cada uno de nosotros tiene un gráfico conectado de las personas en nuestras vidas y las formas en que nuestras relaciones e intereses se superponen.

Estos tipos de datos interconectados son exactamente el desafío que GraphQL inicialmente se propuso resolver en el desarrollo de API. Al escribir una API GraphQL, podemos conectar datos de manera eficiente, lo que reduce la complejidad y la cantidad de solicitudes, al tiempo que nos permite brindarle al cliente precisamente los datos que necesita. (Si le gustan más metáforas de GraphQL, consulte Reunión de GraphQL en un cóctel).

En este artículo, crearemos una API GraphQL en Node.js, utilizando el paquete Apollo Server. Para hacerlo, exploraremos temas fundamentales de GraphQL, escribiremos un esquema GraphQL, desarrollaremos código para resolver nuestras funciones de esquema y accederemos a nuestra API mediante la interfaz de usuario de GraphQL Playground.

¿Qué es GraphQL?

GraphQL es un lenguaje de manipulación de datos y consultas de código abierto para API. Fue desarrollado con el objetivo de proporcionar puntos finales únicos para los datos, permitiendo que las aplicaciones soliciten exactamente los datos que necesitan. Esto tiene la ventaja no solo de simplificar nuestro código de interfaz de usuario, sino también de mejorar el rendimiento al limitar la cantidad de datos que deben enviarse por cable.

lo que estamos construyendo

Para seguir este tutorial, necesitará Node v8.xo posterior y cierta familiaridad con el trabajo con la línea de comandos.

Vamos a crear una aplicación API para los aspectos más destacados de los libros, lo que nos permitirá almacenar pasajes memorables de las cosas que leemos. Los usuarios de la API podrán realizar “CRUD” (crear, leer, actualizar, eliminar) en sus operaciones destacadas:

• Crear un nuevo punto culminante
• Lea un punto destacado individual, así como una lista de puntos destacados
• Actualizar el contenido de un punto destacado
• Eliminar un resaltado

empezando

Para comenzar, primero cree un nuevo directorio para nuestro proyecto, inicialice un nuevo proyecto de nodo e instale las dependencias que necesitaremos:

# make the new directorymkdir highlights-api# change into the directorycd highlights-api# initiate a new node projectnpm init -y# install the project dependenciesnpm install apollo-server graphql# install the development dependenciesnpm install nodemon --save-dev

Antes de continuar, analizamos nuestras dependencias:

• apollo-serveres una biblioteca que nos permite trabajar con GraphQL dentro de nuestra aplicación Node. Lo usaremos como una biblioteca independiente, pero el equipo de Apollo también ha creado middleware para trabajar con aplicaciones web de Node existentes en Express , hapi , Fastify y Koa .
• graphqlIncluye el lenguaje GraphQL y es una dependencia de pares requeridos apollo-server.
• nodemones una biblioteca útil que observará nuestro proyecto en busca de cambios y reiniciará automáticamente nuestro servidor.

Con nuestros paquetes instalados, a continuación creemos el archivo raíz de nuestra aplicación, llamado index.js. Por ahora, enviaremos console.log()un mensaje en este archivo:

console.log("  Hello Highlights");

Para simplificar nuestro proceso de desarrollo, actualizaremos el scriptsobjeto dentro de nuestro package.jsonarchivo para utilizar el nodemonpaquete:

"scripts": {  "start": "nodemon index.js"},

Ahora podemos iniciar nuestra aplicación escribiendo npm starten la aplicación de terminal. Si todo funciona correctamente, verás que Hello Highlightshas iniciado sesión en tu terminal.

Tipos de esquema GraphQL

Un esquema es una representación escrita de nuestros datos e interacciones. Al requerir un esquema, GraphQL impone un plan estricto para nuestra API. Esto se debe a que la API solo puede devolver datos y realizar interacciones definidas dentro del esquema. El componente fundamental de los esquemas GraphQL son los tipos de objetos. GraphQL contiene cinco tipos integrados:

• Cadena: una cadena con codificación de caracteres UTF-8
• Booleano: un valor verdadero o falso
• Int: un entero de 32 bits
• Flotante: un valor de punto flotante
• ID: un identificador único

Podemos construir un esquema para una API con estos componentes básicos. En un archivo llamado schema.js, podemos importar la gqlbiblioteca y preparar el archivo para nuestra sintaxis de esquema:

const { gql } = require('apollo-server');const typeDefs = gql`  # The schema will go here`;module.exports = typeDefs;

Para escribir nuestro esquema, primero definimos el tipo. Consideramos cómo podríamos definir un esquema para nuestra aplicación de aspectos destacados. Para comenzar, crearíamos un nuevo tipo con un nombre de Highlight:

const typeDefs = gql`  type Highlight {  }`;

Cada resaltado tendrá una identificación única, algo de contenido, un título y un autor. El Highlightesquema se verá así:

const typeDefs = gql`  type Highlight {    id: ID    content: String    title: String    author: String  }`;

Podemos hacer que algunos de estos campos sean obligatorios añadiendo un signo de exclamación:

const typeDefs = gql`  type Highlight {    id: ID!    content: String!    title: String    author: String  }`;  

Aunque hemos definido un tipo de objeto para nuestros aspectos destacados, también debemos proporcionar una descripción de cómo un cliente obtendrá esos datos. Esto se llama query. Profundizaremos más en las consultas en breve, pero por ahora describimos en nuestro esquema las formas en que alguien recuperará los aspectos destacados. Al solicitar todos nuestros aspectos destacados, los datos se devolverán como una matriz (representada como [Highlight]) y cuando queramos recuperar un solo resaltado necesitaremos pasar una ID como parámetro.

const typeDefs = gql`  type Highlight {    id: ID!    content: String!    title: String    author: String  }  type Query {    highlights: [Highlight]!    highlight(id: ID!): Highlight  }`;

Ahora, en el index.jsarchivo, podemos importar nuestras definiciones de tipo y configurar el servidor Apollo:

const {ApolloServer } = require('apollo-server');const typeDefs = require('./schema');const server = new ApolloServer({ typeDefs });server.listen().then(({ url }) = {  console.log(`  Highlights server ready at ${url}`);});

Si hemos mantenido el proceso del nodo en ejecución, la aplicación se habrá actualizado y reiniciado automáticamente, pero si no, al escribir npm startdesde el directorio del proyecto en la ventana del terminal se iniciará el servidor. Si miramos la terminal, deberíamos ver que nodemonestá vigilando nuestros archivos y que el servidor se está ejecutando en un puerto local:

[nodemon] 2.0.2[nodemon] to restart at any time, enter `rs`[nodemon] watching dir(s): *.*[nodemon] watching extensions: js,mjs,json[nodemon] starting `node index.js`  Highlights server ready at http://localhost:4000/

Al visitar la URL en el navegador, se iniciará la aplicación GraphQL Playground, que proporciona una interfaz de usuario para interactuar con nuestra API.

Resolutores GraphQL

Aunque hemos desarrollado nuestro proyecto con un esquema inicial y la configuración del servidor Apollo, todavía no podemos interactuar con nuestra API. Para hacerlo, presentaremos resolutores. Los resolutores realizan exactamente la acción que su nombre implica; resuelven los datos que el usuario de la API ha solicitado. Escribiremos estos solucionadores definiéndolos primero en nuestro esquema y luego implementando la lógica dentro de nuestro código JavaScript. Nuestra API contiene dos tipos de solucionadores: consultas y mutaciones.

Primero agreguemos algunos datos con los que interactuamos. En una aplicación, normalmente serán datos que recuperamos y escribimos desde una base de datos, pero para nuestro ejemplo usaremos una matriz de objetos. En el index.jsarchivo agregue lo siguiente:

let highlights = [  {    id: '1',    content: 'One day I will find the right words, and they will be simple.',    title: 'Dharma Bums',    author: 'Jack Kerouac'  },  {    id: '2',    content: 'In the limits of a situation there is humor, there is grace, and everything else.',    title: 'Arbitrary Stupid Goal',    author: 'Tamara Shopsin'  }]

Consultas

Una consulta solicita datos específicos de una API, en el formato deseado. Luego, la consulta devolverá un objeto que contiene los datos que el usuario de la API ha solicitado. Una consulta nunca modifica los datos; solo accede a él. Ya hemos escrito dos consultas en nuestro esquema. El primero devuelve una serie de resaltados y el segundo devuelve un resaltado específico. El siguiente paso es escribir los solucionadores que devolverán los datos.

En el index.jsarchivo, podemos agregar un objeto de resolución, que puede contener nuestras consultas:

const resolvers = {  Query: {    highlights: () = highlights,    highlight: (parent, args) = {      return highlights.find(highlight = highlight.id === args.id);    }  }};

La highlightsconsulta devuelve la gama completa de datos destacados. La highlightconsulta acepta dos parámetros: parenty args. Es parentel primer parámetro de cualquier consulta GraqhQL en Apollo Server y proporciona una forma de acceder al contexto de la consulta. El argsparámetro nos permite acceder a los argumentos proporcionados por el usuario. En este caso, los usuarios de la API proporcionarán un argumento de identificación para acceder a un punto destacado específico.

Luego podemos actualizar nuestra configuración del servidor Apollo para incluir los solucionadores:

const server = new ApolloServer({ typeDefs, resolvers });

Con nuestros solucionadores de consultas escritas y el servidor Apollo actualizado, ahora podemos consultar la API utilizando GraphQL Playground. Para acceder a GraphQL Playground, visite http://localhost:4000su navegador web.

Una consulta tiene el formato siguiente:

query {  queryName {      field      field    }}

Con esto en mente, podemos escribir una consulta que solicite el ID, el contenido, el título y el autor de cada uno de nuestros aspectos destacados:

query {  highlights {    id    content    title    author  }}

Digamos que tenemos una página en nuestra interfaz de usuario que enumera solo los títulos y autores de nuestros textos resaltados. No necesitaríamos recuperar el contenido de cada uno de esos aspectos destacados. En su lugar, podríamos escribir una consulta que solo solicite los datos que necesitamos:

query {  highlights {    title    author  }}

También escribimos un solucionador para consultar una nota individual al incluir un parámetro de ID con nuestra consulta. Podemos hacerlo de la siguiente manera:

query {  highlight(id: "1") {    content  }}

Mutaciones

Usamos una mutación cuando queremos modificar los datos en nuestra API. En nuestro ejemplo de resaltado, querremos escribir una mutación para crear un nuevo resaltado, una para actualizar un resaltado existente y una tercera para eliminar un resaltado. De manera similar a una consulta, también se espera que una mutación devuelva un resultado en forma de objeto, normalmente el resultado final de la acción realizada.

El primer paso para actualizar cualquier cosa en GraphQL es escribir el esquema. Podemos incluir mutaciones en nuestro esquema, agregando un tipo de mutación a nuestro schema.jsarchivo:

type Mutation {  newHighlight (content: String! title: String author: String): Highlight!  updateHighlight(id: ID! content: String!): Highlight!  deleteHighlight(id: ID!): Highlight!}

Nuestra newHighlightmutación tomará el valor requerido del contenido junto con los valores opcionales titley authordevolverá un archivo Highlight. La updateHighlightmutación requerirá que se resalte idy contentse pase como valores de argumento y devolverá el archivo actualizado Highlight. Finalmente, la deleteHighlighmutación t aceptará un argumento ID y devolverá el resaltado eliminado.

Con el esquema actualizado para incluir mutaciones, ahora podemos actualizar resolversnuestro index.jsarchivo para realizar estas acciones. Cada mutación actualizará nuestra highlightsmatriz de datos.

const resolvers = {  Query: {    highlights: () = highlights,    highlight: (parent, args) = {      return highlights.find(highlight = highlight.id === args.id);    }  },  Mutation: {    newHighlight: (parent, args) = {      const highlight = {        id: String(highlights.length + 1),        title: args.title || '',        author: args.author || '',        content: args.content      };      highlights.push(highlight);      return highlight;    },    updateHighlight: (parent, args) = {      const index = highlights.findIndex(highlight = highlight.id === args.id);      const highlight = {        id: args.id,        content: args.content,        author: highlights[index].author,        title: highlights[index].title      };      highlights[index] = highlight;      return highlight;    },    deleteHighlight: (parent, args) = {      const deletedHighlight = highlights.find(        highlight = highlight.id === args.id      );      highlights = highlights.filter(highlight = highlight.id !== args.id);      return deletedHighlight;    }  }};

Con estas mutaciones escritas, podemos usar GraphQL Playground para practicar la mutación de los datos. La estructura de una mutación es casi idéntica a la de una consulta: especifica el nombre de la mutación, pasa los valores de los argumentos y solicita datos específicos a cambio. Comencemos agregando un nuevo punto destacado:

mutation {  newHighlight(author: "Adam Scott" title: "JS Everywhere" content: "GraphQL is awesome") {    id    author    title    content  }}

Luego podemos escribir mutaciones para actualizar un resaltado:

mutation {  updateHighlight(id: "3" content: "GraphQL is rad") {    id    content  }}

Y para eliminar un resaltado:

mutation {  deleteHighlight(id: "3") {    id  }}

Terminando

¡Felicidades! Ahora ha creado con éxito una API GraphQL utilizando Apollo Server y puede ejecutar consultas y mutaciones GraphQL en un objeto de datos en memoria. Hemos establecido una base sólida para explorar el mundo del desarrollo de API GraphQL.

Aquí hay algunos posibles próximos pasos para subir de nivel:

• Obtenga más información sobre las consultas y mutaciones anidadas de GraphQL .
• Siga el tutorial de Apollo Full Stack .
• Actualice el ejemplo para incluir una base de datos, como MongoDB o PostgreSQL.
• Explore más artículos fantásticos de GraphQL sobre CSS-Tricks .
• Utilice su nuevo conocimiento de GraphQL para crear sitios web estáticos con Gatsby .