Redbox Move to GraphQL

In Redbox, we moved to using GraphQL as a fa?ade for the backend facilitating client application development and backend changes.

What is GraphQL?

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

GraphQL (https://graphql.org/) has grown in last few years into a well-known technology used to simplify development of applications using some backend. It is now used by companies that expose large systems for integrations by client applications, such as Facebook or GitHub.

In Redbox, GraphQL was first used as a technology to implement replacement APIs for the external CSG dependency. It is now evolving toward a goal of being a fa?ade for all public or user specific data used by Redbox applications for CE and mobile devices.

Why GraphQL?

GraphQL was invented with an idea to solve some of the struggles associated with the use of classical REST services by clients. Problems that client development usually had with RESTful services:

• Resource based APIs where the breakdown of resources was defined statically, not aligned with the client use.
• Resources contain data that might or might not be needed by specific client; data is transferred always.
• To get a larger graph of interconnected resources clients need to execute multiple or many requests adding a large overhead both to client device and the server.

In contrast, GraphQL offers a systematic way of enabling clients to get the structure they want with data they want, in one request. GraphQL exposes a schema showing:

• Which objects are available, and their hierarchy (products, devices, pricing…)
• Which fields are available in objects and their types (supporting built-in types, custom base types, objects, lists, non-nulls)
• Which parameters (filters) are available when asking for a field
• Mutations (intended to change data)
• Deprecation warnings
• Additional metadata (descriptions, examples)

Usage

Basically, GraphQL is invoked over an HTTP client, like most of the APIs today. In the route you need to target the root path of GraphQL service. In the body a request query or mutation should be sent with optional variables section. The format of the request is a GraphQL request syntax and is a standard. Once the request is executed, in the response you can expect a JSON with two main sub-sections: data and errors.

GraphQL does not return HTTP status codes to indicate specific error cases. It always returns a 200 OK status, and notifies the client of any specific errors in the errors section. This enables the request to be partially successfully executed (such as when user is not authorized for parts of the query).

an example of a query, variables and the response with GraphiQL — GraphQL IDE (GitHub — graphql/graphiql)

Since GraphQL is a mature technology, there’s a plenty of implementations for backend, frontend and devices. Mostly used backend libraries for .NET are: HotChocolate (https://chillicream.com/docs/hotchocolate/v10), GraphQL-dotnet (https://github.com/graphql-dotnet/graphql-dotnet). For Java it’s GraphQL Java (https://www.graphql-java.com/). For frontend the usual choices are: URQL (https://github.com/FormidableLabs/urql), Apollo or Relay. Apollo is the usual choice for mobile development too (https://www.apollographql.com/docs/android/).

When developing against a GraphQL server, it is convenient to be able to try it out, before coding. Tools mostly used for this are: GraphQL Playground, Postman, GraphiQL and Insomnia.

GraphQL is not a silver bullet for system architecture challenges. It is well designed to offer a fa?ade for clients, but it does not imply the backend implementation. It can have an array of micro-services, different storages or a cache as a backend. It is able to expose a combination of different sources without leaking their implementation. Because of its core feature of aggregation, it is behaving more like a monolithic gateway to the system. While libraries for certain sources already exist, it is very easy to provide a source of your own.

a typical architecture with GraphQL - a client-oriented fa?ade hiding details of a backend

GraphQL in Redbox

In Redbox we use it to provide a fa?ade over a cluster of micro-services with different contracts and organizing resources together even if they’re in several different micro-services or external systems.

It was initially built to replace OnDemand backend APIs exposing several domains: device management, products, wish list, digital locker, digital pricing, digital purchase, transactions, playback streams and playback progress. As a second phase, it exposes additional domains like user profile, opt-ins, perks, kiosks, inventory, physical pricing, physical disk reservation and transactions.

Parts of the schema is offered for query as public like product metadata or pricing, while others are restricted to specific user.

GraphQL integrates data from quite-a-few services, some in Google Cloud Platform Kubernetes cluster, some in AWS and some in Data Center. GraphQL also uses some data storages directly like Firestore and uses event infrastructure like GCP’s PubSub.

In backend we use Chilly Cream’s Hot Chocolate GraphQL library that has proven itself as stable, maintained and extensible. In client side we use URQL for front-end clients and Apollo for mobile clients. While GraphQL can be called from clients with a simple HTTP client, libraries help manage payloads, error handling and versioning better.

We track performance of GraphQL with real-time metrics implemented with Prometheus and Grafana. These metrics are scoped to all fields, as well as usual queries and deprecated fields. Longer-living event metrics are available through sending events to BigQuery.

Benefits

With GraphQL in place for OnDemand and physical, we already reaped several of the general benefits of GraphQL.

With contracts where clients are able to pick-and-choose, mobile, TV clients and web are executing slightly different requests against the GraphQL and have already changed their requests few times. All that without GraphQL contracts being changed, and all the time with minimal response sizes needed.

With GraphQL in place as a fa?ade, backend was evolving and several internal dependencies were changed as part of the Jarvis initiative. Some of the examples are Personalization being replaced with Loyalty and Customer Profile, and Store being replaced with Kiosk Master Data, Inventory and Physical Pricing. These changes were executed in a way that did not impact clients in any way.