Crea tu primera API GraphQL con AWS AppSync

Tenemos mucho que compartir sobre este tema. Así que si quieres aprender al respecto mantente atento.

Primero debes saber que divideremos la información en dos partes:

En este artículo abordaremos los conceptos básicos de GraphQL, además diseñaremos una API sencilla desde cero y la desplegaremos con el servicio AWS AppSync y serverless framework.

En la siguiente parte crearemos una aplicación del lado del cliente para consumir la API. Utilizaremos el framework Amplify+ReactJS y además daremos más funcionalidades a nuestra API mediante el uso de suscripciones para un caso de uso en tiempo real.

¿Qué es GraphQL?

Graphql es un lenguaje de consulta de datos para API, la idea fundamental es hacer que la API esté disponible a través de un único endpoint, en lugar de acceder a varios como se hace actualmente con REST.

Entre las ventajas de GraphQL podemos nombrar las siguientes:

• El cliente puede especificar exactamente la estructura de los datos que serán servidos.
• Carga de datos eficiente, mejorando en gran medida el uso del ancho de banda.
• Estilo declarativo y auto-documentativo gracias a los esquemas fuertemente tipados.

Esquemas

Los esquemas determinan la capacidad de la API y definen tres operaciones fundamentales: query, mutation, subscription. También incluye los parámetros de entrada y las posibles respuestas.

Solucionadores

Los solucionadores implementan la API y describen el comportamiento del servidor. Básicamente son funciones que se encargan de obtener datos para cada campo definido en el esquema.

AWS Appsync+Serverless Framework

AppSync es un servicio serverless gestionado por AWS, es una capa de GraphQL que nos permitirá desarrollar nuestra API de manera ágil. Es importante conocer los componentes básicos de AppSync:

• Esquema: como lo mencionamos anteriormente aquí definiremos los tipos y operaciones básicas para recuperar y guardar los datos.
• Solucionadores: define las plantillas de mapeo de solicitud y respuesta para cada campo definido en el esquema. Están escritas en VTL y se encargan de interpretar las respuestas de las fuentes de datos y también analizan las solicitudes.
• Fuentes de datos: integración con los servicios de AWS: DynamoDB, Lambda, RDS y ElasticSearch.
• Autenticación: podemos autenticar la API con API_KEY, IAM o Cognito User Pools

Como podemos ver AppSync proporciona algunas herramientas para construir una API GraphQL de manera fluida, se puede seguir una serie de pasos desde la consola de AWS AppSync y en cuestión de minutos podemos tener algo funcional. Sin embargo preferimos hacerlo de una forma más cercana a la realidad de aplicaciones modernas en producción.

Aquí entra en juego serverless framework una tecnología robusta para definir la infraestructura como código orientado a aplicaciones serverless para diferentes proveedores cloud. En Kushki creemos que hoy en día es crucial tener una infraestructura serverless versionada y automatizada, veremos que es una forma práctica y eficiente de implementar nuestra API. Serverless tiene varias opciones para desplegar AppSync en la nube.

Sin más empecemos a poner en práctica todos estos conceptos mediante una sencilla aplicación.

La aplicación: To do List

En esta primera parte del artículo crearemos la API GraphQL de un CRUD To do List. Usaremos DynamoDB para la base de datos.

Requisitos:

• NodeJS
• Cuenta en AWS (credenciales configuradas)
• Serverless Framework

Empecemos instalando serverless y un plugin para Appsync:

npm install -g serverless serverless-appsync-plugin

En el directorio principal del proyecto ejecutamos el siguiente comando para crear una plantilla con las configuraciones necesarias para crear una aplicación serverless en AWS.

serverless create --template aws-nodejs

Nota: agrega serverless-appsync-plugin en la sección plugins del archivo serverless.yml:

Primero definimos parte de nuestra infraestructura. Para esto, crearemos una tabla todos en DynamoDB en serverless.yml. Por el momento no nos preocuparemos sobre las diferentes configuraciones, con el siguiente fragmento de código bastará:

resources:  
  Resources:  
    todos:  
      Type: "AWS::DynamoDB::Table"  
  Properties:  
        TableName: todos  
        AttributeDefinitions:  
          - AttributeName: id  
            AttributeType: S  
        KeySchema:  
          - AttributeName: id  
            KeyType: HASH  
        BillingMode: PAY_PER_REQUEST

Define un esquema GraphQL

En la raíz crea un archivo schema.graphql. Aquí es donde definimos nuestro esquema y los tipos de datos. Por el momento definiremos las operaciones query y mutation. GraphQL maneja su propia sintaxis llamada SDL, aquí puedes revisar mas sobre este tema.

schema {  
    query: Query  
    mutation: Mutation  
}  
  
type Query {  
    listToDos: [ToDo]  
    getToDoById(id: ID!): ToDo  
}  
  
type Mutation {  
    createToDo(input: CreateToDoInput!): ToDo  
    updateToDo(input: UpdateToDoInput!): ToDo  
    deleteToDo(id: ID!): Boolean  
}  
  
type ToDo {  
  id: ID!  
  name: String  
  title: String!  
  description: String  
  completed: Boolean!  
}  
  
input CreateToDoInput {  
  id: ID!  
  name: String!  
  title: String!  
  description: String!  
  completed: Boolean!  
}  
  
input UpdateToDoInput {  
  name: String!  
  title: String!  
  description: String!  
  completed: Boolean!  
}

Recordemos que para cada campo definido se requiere implementar un solucionador. En este caso los solucionadores son consultas a DynamoDB escritas en VTL. Existen algunas funciones de utilidad que hacen más fácil su implementación, para más información de plantillas de mapeo de solucionadores puedes visitar este link.

Solucionador createToDo:

Creamos un directorio mapping-templates en la raíz del proyecto donde alojamos los solucionadores de petición y respuesta por cada campo creado en el esquema.

Petición: crear archivo createToDo-request.vtl e insertar el siguiente código:

{  
    "version" : "2017-02-28",  
    "operation" : "PutItem",  
    "key" : {  
        "id" : $util.dynamodb.toDynamoDBJson($context.arguments.input.id)  
    },  
    "attributeValues" : {  
        "name" : $util.dynamodb.toDynamoDBJson($context.arguments.input.name),  
        "title" : $util.dynamodb.toDynamoDBJson($context.arguments.input.title),  
        "description" : $util.dynamodb.toDynamoDBJson($context.arguments.input.description),  
        "completed" : $util.dynamodb.toDynamoDBJson($context.arguments.input.completed)  
    }  
}

Con la variable $context.argument podemos acceder a los parámetros de entrada que hemos definido en nuestro esquema.

Respuesta: crear archivo createToDo-response.vtl e insertar el siguiente código:

$utils.toJson($context.result)

No te preocupes en como se obtienen los datos desde DynamoDB, AppSync realiza la conexión con las fuentes de datos, los devuelve en la variable $context.result y $utils.toJson lo presenta en un formato entendible para GraphQL. Si deseas procesar estos datos en el solucionador lo puedes hacer con VTL.

Solucionador updateToDo:

Petición: crear archivo updateToDo-request.vtl e insertar el siguiente código, en este caso usaremos una operación de UpdateItem de DynamoDB:

{  
    "version" : "2017-02-28",  
    "operation" : "UpdateItem",  
    "key" : {  
        "id" : $util.dynamodb.toDynamoDBJson($context.arguments.input.id)  
    },  
    "update" : {  
        "expression" : "SET name = :name, title = :title, description = :description, completed = :completed",  
        "expressionValues": {  
            ":author" : $util.dynamodb.toDynamoDBJson($context.arguments.input.name),  
            ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.input.title),  
            ":content" : $util.dynamodb.toDynamoDBJson($context.arguments.input.description),  
            ":url" : $util.dynamodb.toDynamoDBJson($context.arguments.input.completed)  
        }  
    }  
}

Respuesta: crear archivo createToDo-response.vtl e insertar el siguiente código:

$utils.toJson($context.result)

Solucionador getToDoById:

Petición: crear archivo getToDoById-request.vtl e insertar el siguiente código:

{  
    "version" : "2017-02-28",  
    "operation" : "GetItem",  
    "key" : {  
        "id" : $util.dynamodb.toDynamoDBJson($context.args.id)  
    }  
}

Respuesta: crear archivo getToDoById-response.vtl e insertar el siguiente código:

$utils.toJson($context.result)

Definimos nuestra infraestructura de AppSync y el archivo servereless.yml en donde definimos los solucionadores (mappingTemplates), esquema (schema), fuente de datos(dataSources) y el tipo de autenticación(authenticationType), debería tener la siguiente estructura, :

service:  
  name: appsync-todo-app-backend  
  
plugins:  
  - serverless-appsync-plugin  
  
custom:  
  appSync:  
    name: todo-app  
    authenticationType: API_KEY  
    mappingTemplates:  
      - dataSource: todos  
        type: Mutation  
        field: createToDo  
        request: "createToDo-request.vtl"  
		response: "createToDo-response.vtl"  
	  - dataSource: todos  
        type: Mutation  
        field: updateToDo  
        request: "updateToDo-request.vtl"  
		response: "updateToDo-response.vtl"  
	  - dataSource: todos  
        type: Query  
        field: getToDoById  
        request: "getToDoById-request.vtl"  
		response: "getToDoById-response.vtl"  
  schema: # defaults schema.graphql  
  dataSources:  
      - type: AMAZON_DYNAMODB  
        name: todos  
        description: 'Todos table'  
  config:  
      tableName: todos  
  
provider:  
  name: aws  
  runtime: nodejs12.x  
  
resources:  
  Resources:  
    todos:  
      Type: "AWS::DynamoDB::Table"  
  Properties:  
        TableName: todos  
        AttributeDefinitions:  
          - AttributeName: id  
            AttributeType: S  
        KeySchema:  
          - AttributeName: id  
            KeyType: HASH  
        BillingMode: PAY_PER_REQUEST

Finalmente ejecutamos el siguiente comando para desplegar nuestra API en la nube de AWS:

serverless deploy

Probando nuestra API GrapQL:

Si abrimos la consola de AWS AppSync veremos el esquema, los solucionadores, la autenticación y la fuente de datos que hemos definido.

Por otro lado también tenemos un cliente GraphQL con el cual podemos realizar pruebas de nuestra API. En la siguiente figura podemos observar la documentación de la API de acuerdo a los esquemas definidos.

Al ejecutar la operación de mutación createToDo se crea un registro en DynamoDB y devuelve el objeto creado según los campos definidos.

Para recuperar los datos de un ToDo ejecutamos la operación query de getToDoById, podemos solicitar solo el campo name o los que sean necesarios.

Ahí lo tuviste:

En este artículo abordamos los conceptos básicos de GraphQL, además diseñamos una API sencilla desde cero y la desplegamos con el servicio AWS AppSync y serverless framework.

Recuerda que aún queda una siguiente parte, en la que crearemos una aplicación del lado del cliente para consumir la API. Utilizaremos el framework Amplify+ReactJS y además daremos más funcionalidades a nuestra API mediante el uso de suscripciones para un caso de uso en tiempo real.

Te esperamos en la segunda parte de este artículo.