Testing AppSync GraphQL with Altair

GraphQL[1] has been presented as a revolutionary alternative and the hottest new trend for APIs. AWS AppSync[2] is a fully managed service that makes it easy to develop GraphQL APIs in the AWS environment. AWS AppSync has its own mechanism to authenticate over WebSocket for the GraphQL SUBSCRIPTION operation[3], most of the GraphQL GUI clients/testing tools do not support SUBSCRIPTION in AppSync. This article is going to demonstrate how to set up the Altair GraphQL Client[4] latest version to work with AWS AppSync with SUBSCRIPTION supported.

 TL;DR - Jump to the setting instruction

GraphQL SUBSCRIPTION

Two operations, QUERY (retrieving the data, equivalent to SELECT in SQL, or HTTP GET operation) and MUTATION (alter the data, equivalent to INSERT/UPDATE/DELETE in SQL or HTTP POST/PUT/PATCH/DELETE operations) were the only operations defined in the initial specification[5]. In order to allow the real-time streams of data over a single TCP connection, SUBSCRIPTION was introduced in June 2018[6]. Most of the libraries [7, 8] have implemented SUBSCRIPTION with the WebSocket[9].

The issue facing in testing GraphQL with AppSync

I used the third-party GUI clients, such as Postman and SOAPUI, to test the external APIs when I worked on the integration between different systems with CMS in my previous position.

We develop our GraphQL APIs with AWS AppSync in Zeller. In theory, I can use the same strategy to test GraphQL API endpoint before writing my own code. Even though there are serval GraphQL GUI clients on the market, most of them are not supported the GraphQL subscription operation in AppSync due to the AWS authentication model. Queries tool in AWS AppSync web console also did not function with the subscription. You have to write your own code to test the GraphQL SUBSCRIPTION operation, but once the code goes wrong, it takes time to find out if it is the problem related to the server or your testing code.

Altair with AWS AppSync support

Altair had added the AWS AppSync support in version 3.0[10]. It supports authentication with API Key. I have submitted an issue[11] and the corresponding Pull Request to add the support of OpenID Connect and Amazon Cognito User Pools authentications. (Both them are using JWT token). Make sure you are using version 3.2.o or above, if you need to set up GraphQL with OpenID Connect or Amazon Cognito User Pools., you need to build the software from the stable branch in the official GitHub repo (Build Instruction).

Steps to setup Altair

Set the AWS AppSync Authentication for GraphQL Document, QUERY and MUTATION Operations

• Get the AWS AppSync GraphQL Endpoint, e.g. https://example1234567890000.appsync-api.us-east-1.amazonaws.com/graphql
• Set value of the Enter URL field to your AWS AppSync GraphQL Endpoint.
• Set the following HTTP Headers
  • HOST – the AWS AppSync GraphQL endpoint
  • X-API-KEY – (API_KEY Authentication only) the corresponding API Key in the AWS App Sync
  • AUTHORIZATION – (OPENID_CONNECT or AMAZON_COGNITO_USER_POOLS Authentication) a valid JWT Access Token

• Press the refresh button next to the Enter URL field to refresh the GraphQL Document, you should not face 401 Authentication error if the setting is correct. You can view the Document by using Docs button
• GraphQL operations QUERY and MUTATION are ready to use

Set up the AWS AppSync Authentication for SUBSCRIPTION Operation

• Setup the Subscription URL with the following parameters.
  • URL – AWS AppSync GraphQL Endpoint or {{aws_appsync_graphqlEndpoint}}
    • Do not use the realtime URL (wss://). The library will convert AWS AppSync GraphQL Endpoint to the corresponding realtime URL
  • Select AWS AppSync
  • Connection parameters in JSON format
    • aws_project_region – AWS Region abbreviation
    • aws_appsync_graphqlEndpoint – AWS AppSync GraphQL Endpoint
    • aws_appsync_region – AWS Region abbreviation
    • aws_appsync_authenticationType – one of the following
      • API_KEY
      • OPENID_CONNECT, or
      • AMAZON_COGNITO_USER_POOLS
    • aws_appsync_apiKey – (API_KEY Authentication only) API Key
    • aws_appsync_jwtToken – (OPENID_CONNECT or AMAZON_COGNITO_USER_POOLS Authentication) JWT Token

After the setup completed, GraphQL operation SUBSCRIPTION is ready to use.

Reference:

1. GraphQL – A query language for your API
2. AWS AppSync – Accelerate application development with scalable GraphQL APIs
3. Building a Real-time WebSocket Client
4. Altair GraphQL Client
5. Section 2.2 Operations, GraphQL initial public release (July 2015 release), published as a work in progress
6. Release notes – GraphQL June 2018 Release
7. Subscriptions | Apollo GraphQL
8. GraphQL Subscriptions | DGraph
9. The WebSocket API (WebSockets)
10. AppSync subscription support
11. Add the Amazon Cognito user pools and OpenID Connect support for AWS AppSync Subscription