The SysGO™ API with GraphQL and Apollo Server

By Matthew Hinton, Senior Developer

Systech Corporation is developing a new generation of support technologies for their customers to manage deployments of Systech gateways and IoT devices. The new platform will be called SysGO™ (Systech Gateway Operations). The first step of this process will be to offer a new API allowing clients to access operational data. All SysGO™ services will be built upon this API, for which customers pay according to usage. 2wav is developing this API for Systech in GraphQL, using the Apollo GraphQL Server.

What is GraphQL?

GraphQL is a self-describing query language that allows clients to see exactly what data and operations are available and to ask for the exact data they need. It was originally developed by Facebook and has been adopted by other major companies including Shopify, Instagram, Twitter and Medium, to name a few. In the world of API design, it’s what all the cool kids are doing.

Apollo Server is an implementation of the GraphQL Schema Definition Language (SDL). We model the client’s existing data in SDL, which defines queries, parameters, and data types. The interface tells you the types field properties; e.g., UID is an integer, name is a string, etc. It allows the client to see immediately what they can do with the data that is available.

Before GraphQL, the most common way to set up a data API like this was to use REST design principles. That’s fine, but it usually requires outside documentation to describe the API, and the client has to develop a custom programming interface. GraphQL has available clients for every language, many with helpful user interfaces where you can immediately see what is available to you, and you can make requests against that data. Apollo Server provides its own Explorer, in which a user can build and run queries, and all of the documentation is right there. For many Systech customers, the SysGO™ GraphQL Explorer will be all the interface they need.

GraphQL Advantages

• Allows adding an API endpoint to existing data sources rapidly.
• Provides a single endpoint and lets consumers precisely query for the data they need.
• Supports Mutations for modifying data and Subscriptions for real-time notifications.
• Great for aggregating data from multiple sources and works well with complex frontends that have rapidly changing data needs.

How did we implement the SysGO™ API?

The Apollo Server is one of the most popular GraphQL server implementations. It gives us this interface and does all the processing of the queries and mapping properties to the response. The group behind the Apollo server has done a lot to popularize GraphQL. Although there are other GraphQL implementations, we’ve used Apollo libraries in our other projects. Being quite familiar with them allowed us to get up and running quickly.

The GraphQL schema definition language is a type language. In the schema definition, we declare a type called user, for example. All the properties have these types. In the implementation we use mostly Typescript to maintain the type safety.

We created the schema definition, then we created the resolvers. Resolvers return the data requested in the query. We can restrict the data returned based on the user’s privileges. An administrator might receive different results from a subscriber, for example.

Clients specify the exact required fields in nested queries, and the server returns optimized payloads containing just those fields.

The initial SysGO™ accesses an existing Systech relational database. We’re using a typescript based ORM call Drizzle which allows us to build up queries in typescript, which turns into a SQL query that executes against the database and returns a result in typescript that is easily returned by the GraphQL resolver.

What is special about the SysGO™ API?

The special requirement of the SysGO™ API is that it will be the basis of a new revenue stream for Systech Corporation. It’s a standard cloud service billing model, where you pay for the amount of service that you use. Each executed operation has a cost in a metric that we call GO.

One thing we’re doing that most other services don’t do is estimate costs. With most other usage based services you don’t know what it’s going to cost you until you get the bill at the end of the month. With ours, you can pass along the query arguments and get estimated costs only, without the data response. A customer could compare running several small queries against a big one and see how that impacts their costs.

It’s been a fun project. Systech customers have been asking for easier and more flexible ways to access their data. Now they have it, and Systech has a new revenue source as well.