Recently I’ve been commissioned to find out ways to create APIs on AWS to be consumed by web and native mobile clients.

---

The landscape is pretty simple. For a classic REST API one can use the Amazon API Gateway service. For GraphQL the AWS AppSync.

At the first sight everything is easy: choose a service. After digging in — for REST all gets complicated while GraphQL stays clean.

Reasons

AppSync / GraphQL has better automation. All additional services needed by the API (functions, data, storage, authorization) are integrated, made quasi-invisible, or configurable with a single click. One has to manage a single umbrella service with an official toolchain. That’s all.

The REST API Gateway turns out it’s just one piece of the puzzle. Unlike AppSync it is not enough to provide an API alone. It needs to be connected manually at least with AWS Lambda and DynamoDB — standalone services for functions and data.

Instead of one service REST ends up with three. Three times more work? On management yes, on coding more. Since REST has no code generators like GraphQL all code has to be written manually. That results in more work by a magnitude.

There are third party generators, tools and frameworks to help. In fact there is an entire industry built around making REST APIs work on Amazon — it is that complicated.

While in a few days it was possible to set up AppSync with React and play thoughtfully with optimizations and experience (Relay vs. Apollo) — spending the same time with the REST API was enough only to create and manage the schema. Adding the necessary Lamdba functions and data backend was unsuccessful with generators and tools provided by the ecosystem.

REST

Image credits: https://iotdemos.wordpress.com

To catch the glimpse of the REST on AWS complexity one should watch these official videos. The first deals with the difficulty to create an API and the second with the difficulty of ensuring best practices.

Following the advice from the videos one should use the recommended tools to achieve better results faster:Swagger, Serverless, Claudia.js — or even try Amazon’s own Amplify.

My personal experience: no success. Bugs, outdated code and documentation, undocumented features, frightening amount of code to be written.

The conclusion left is that AWS REST APIs are of past, complicated, and expensive.

GraphQL

GraphQL is the successor of REST. It offers the following advantages:

1. Flexible API

GraphQL needs no versioning. One of the pain points of REST APIs was to iterate over versions yet keep it transparent to API clients and end users.

GraphQL removes that and keeps the development and maintenance time smaller.

2. Data-driven apps with real-time and offline capabilities

REST APIs were an artifact before the mobile era. They simply served atomic data per atomic requests. Like a list of all articles for the /articles URL. Nothing more.

With mobile devices the requirements changed: there is a need for smarter and low-bandwidth queries (composed on the fly versus the usual REST CRUD operations) which even can be pushed without request (real-time) and are resilient when network services are unavailable (offline capabilities).

A GraphQL app can request all articles together with authors, comments and likes in a single query. This data is automatically cached locally for offline access, and when one of its part is updated (let’s say new article added) the new data is pushed to the device and visualized automatically.

A complete example of a GraphQL stack is the Facebook 2019 redesign and rewrite.

AppSync

AppSync is Amazon’s GraphQL service. Manages the API schema, the queries for the schema, the data sources attached to a schema, and the functions / business logic reused across the schema / app.

The great thing, the magic of AppSync is that one has to work only on the schema and forget the rest.

After defining the schema you’ll get all GraphQL queries, mutations and subscriptions automatically generated with a single click. And a public URL with a working API out of the box.

Next, by using the AWS Amplify Framework — a command line tool to create, manage and implement Amazon web services — with a few simple commands everything else can be set up again, like data, authentication, storage bindings; hosting and even various web and mobile clients to consume the API.

With AppSync and Amplify one can have a mobile-friendly API server and client in … minutes. Once a schema is done the rest is done by AWS.

Summing up

Resources

• The Amazon API Gateway
• AWS AppSync
• The AWS Amplify Framework
• Building the New facebook.com with React, GraphQL and Relay
• Deploy a REST API using Serverless, Express and Node.js
• Building a REST API in Node.js with Lambda, API Gateway, DynamoDB, and Serverless framework
• Building API-Driven Microservices with Amazon API Gateway - AWS Online Tech Talks
• Best Practices for Building Enterprise Grade APIs with Amazon API Gateway - AWS Online Tech Talks
• Swagger
• Serverless
• Claudia.js