API GraphQL con TypeScript: tutorial paso a paso para principiantes

Introducción a GraphQL y TypeScript

GraphQL es un lenguaje de consultas para API que permite a los clientes solicitar únicamente los datos que realmente necesitan. Combinado con TypeScript, que añade tipado estático a JavaScript, obtienes una herramienta poderosa para crear API robustas y escalables. En este tutorial, crearemos paso a paso una API GraphQL simple en TypeScript. Aprenderás a configurar el proyecto, definir el esquema, escribir resolutores y realizar consultas.

Este material está dirigido a desarrolladores principiantes que conocen los fundamentos de JavaScript y desean dominar tecnologías modernas. Al final del artículo, podrás implementar por tu cuenta un servidor GraphQL básico.

Paso 1: Configuración del proyecto

Antes de escribir código, es necesario inicializar el proyecto e instalar las dependencias. Usaremos Apollo Server, una de las bibliotecas más populares para trabajar con GraphQL en Node.js.

Inicialización de npm

Crea un nuevo directorio y ejecuta la inicialización:

mkdir graphql-typescript-tutorialcd graphql-typescript-tutorialnpm init -y

Instalación de dependencias

Instala los paquetes necesarios:

npm install apollo-server graphqlnpm install typescript ts-node @types/node --save-dev

• apollo-server — servidor para procesar consultas GraphQL.
• graphql — núcleo del lenguaje GraphQL.
• typescript y ts-node — para compilar y ejecutar TypeScript.

Configuración de TypeScript

Crea el archivo tsconfig.json en la raíz del proyecto:

{  "compilerOptions": {    "target": "ES2020",    "module": "commonjs",    "strict": true,    "esModuleInterop": true,    "outDir": "./dist",    "rootDir": "./src"  },  "include": ["src/**/*"],  "exclude": ["node_modules"]}

Crea la carpeta src y el archivo index.ts — allí estará el código principal del servidor.

Paso 2: Definición del esquema y tipos

El esquema GraphQL describe qué datos están disponibles y cómo se pueden consultar. En TypeScript, usaremos una cadena con sintaxis gql para definir los tipos.

Esquema básico

Abre src/index.ts y agrega el siguiente código:

import { ApolloServer, gql } from 'apollo-server';

const typeDefs = gql`  type Book {    id: ID!    title: String!    author: String!  }

  type Query {    books: [Book]    book(id: ID!): Book  }`;

Aquí definimos el tipo Book con los campos id, title y author. Query contiene dos consultas: obtener todos los libros y un libro por ID.

Datos simulados

Para pruebas, agreguemos un arreglo de libros:

const books = [  { id: '1', title: 'Guerra y Paz', author: 'León Tolstói' },  { id: '2', title: 'Crimen y Castigo', author: 'Fiódor Dostoyevski' },];

Paso 3: Escritura de resolutores

Los resolutores son funciones que devuelven datos para cada campo del esquema. Conectan el esquema con los datos reales.

Implementación de resolutores

Agrega el objeto resolvers:

const resolvers = {  Query: {    books: () => books,    book: (_: any, args: { id: string }) => {      return books.find(book => book.id === args.id);    },  },};

El primer argumento _ es el objeto padre (no se usa en este caso). El segundo argumento args contiene los parámetros de la consulta, por ejemplo, id.

Montaje del servidor

Ahora creemos una instancia del servidor y ejecútalo:

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

server.listen().then(({ url }) => {  console.log(`🚀 Servidor iniciado en ${url}`);});

Completo