What you need in GraphQL API Management (Walk a mile in GraphQL’s shoes)

Pop quiz:  You’ve been using an API Management solution for a few years now with REST APIs and a few SOAP APIs. What’s the most important thing you need as you start adding GraphQL APIs into the mix?

Answer: Consistency.

You have many APIs today:

• you manage them in an API Manager
• you socialize them in a Developer Portal
• you analyze them with an Analytics tool
• you enforce and secure them with an API Gateway
• you monetize them with API Products and API Plans

The most important thing when you start introducing GraphQL APIs into your mix is that they fit into this architecture. To start with, your API consumers should discover your new GraphQL APIs in your Developer Portal the same way that they discover your REST and SOAP APIs.

Developer Portal

Of course, it has to be a deep integration: your new GraphQL APIs have to live side-by-side with your REST APIs in the same API Products and API Plans. This isn’t a new idea: when someone subscribes to one of your API Products and pays you for it, that single product has always included a variety of APIs, grouped by the function they provide as a product.

Analogy: Shoes

As an analogy, let’s take the innovation from about 200 years ago of left & right shoes. You might know that shoes had sometimes been specialized for left and right, but as Wikipedia writes:

Until around 1800, welted rand shoes were commonly made without differentiation for the left or right foot.

Imagine a cobbler deciding to specialize, designing and preparing left and right shoes. In walks his first customer and he offers them two separate products: a right shoe and a left shoe. Meanwhile, his competitor across the street copies his idea and innovates the business model: he sells a single product that includes both a left shoe and a right shoe.

Did the second cobbler really innovate? Of course not — he continued the age-old business model of selling a pair of shoes. It’s the first cobbler who innovated by breaking the business model and trying to sell them separately just because he made them differently and for different purposes. Sure, some products are separate - like shoes and a hat. Other parts really form a single product - like a pair of shoes.

Hopefully the analogy is obvious. For years, you’ve already divided your APIs into buckets, and offered each bucket as an API Product that you market, socialize, and sell as a single unit. If one of those APIs in that API Product happens to be a GraphQL API or a REST API, then you really shouldn’t force your API consumers to buy it in a separate product.

You want your API consumer to discover your API Product, browse the API Plans offered for it, and pay money to purchase it — all without differentiating the type of API.

Here’s a picture of a ficticious bank’s Developer Portal offering an Online Banking product. This product is the ‘full service’ needed to build an online banking application that runs against the bank’s APIs. It includes three APIs:

• An old SOAP API used to retrieve bank account data
• An old REST API used to submit an application for a credit card
• A new GraphQL API used to retrieve bank account and bank customer data

The GraphQL API might offer new functionality beyond the SOAP API, or it might mostly be a different API providing the same underlying functionality like GitHub’s v3 REST API and v4 GraphQL API.

The key here is that it’s a single product offered to fulfill the single purpose of online banking, while it comprises SOAP, REST, and GraphQL APIs. And then that product offers applications to subscribe to API Plans, with details about the APIs available, but is still sold as a single product:

But like left shoes should be tried out on the left foot only, GraphQL APIs need to be tried out with an appropriate client like GraphiQL or GraphQL Playground, and not just the same tools we use for REST. And since GraphQL APIs allow the consumer to control the contract for each transaction, they have to charge money based on the complexity or cost of the data requested through them, and not based on the raw numbers of transactions.

Gold Plan

In this picture we navigate in the Developer Portal to the “Try It” tab for our new GraphQL API, and try it with our Premium Online Banking Application’s subscription to the Gold Plan:

• In the left pane, it allows us to query for multiple accounts
• In the middle pane, we see successful results from trying that API call
• In the right pane, we see documentation for queries for both a single account and multiple accounts

Silver Plan

Next we switch to our Simple Mobile Banking Application’s subscription to the Silver Plan:

• In the left pane, it flags our use of accounts as an illegal query
• In the middle pane, we see a validation failure if we try to use accounts
• In the right pane, we see documentation that shows only single-result queries like account

There’s no rocket science here. This is the well-known standard open source GraphiQL UI, automatically adapting itself to each subscription via introspection. The important part is that the GraphQL API’s “Try It” tab is tailored to the right way to try out a GraphQL API, while the REST and SOAP API’s are tailored to REST and WSDL, respectively.

In summary, just like left and right shoes, APIs must be offered and sold as unified products, while showing their features and testing them in a specialized manner.

Analytics

The same considerations apply to your Analytics node. Today, when an API transaction runs within an API Product and API Plan, your analytics data shows your transactions in that context, but is also searchable as the API itself regardless of the context that it ran in. That has to stay the same when you introduce GraphQL APIs, matching how you are marketing and selling them.

The particulars are all augmented. In addition to all the data you need for REST APIs — such as headers, payloads, memory statistics, and latency timings — GraphQL gives us much finer-grained knowledge of what the API consumer is requesting, and what information you have returned to them. This fine-grained knowledge has great promise for the degree to which you can understand and improve your API, but obviously only when your Analytics engine provides you the data.

This also relates directly to a key GraphQL challenge: GraphQL APIs are usually not versioned, which gives you an extra burden of understanding exactly how your API is being used so that you can know when to deprecate and remove functionality. Fortunately, all those extra fine-grained insights can help, especially in a well-designed analytics system.

Rate Limiting

Rate Limits apply to a whole API Plan and all of its APIs, but as I discussed, per-transaction limits aren’t good enough for GraphQL APIs. Of course all of the GraphQL APIs in a single API Plan can still share rate limits on the GraphQL cost, and all APIs can share the per-transaction limits.

The key is for the API consumer to understand what rate limit they will be offered before sending the transaction at all, specifically for their API Plan, or for the plan which they are considering. Here we see, for a single subscribed API Plan and set of rate limits on a single banking API,

• a small GraphQL query being allowed 500 transactions in each interval
• a medium GraphQL query being allowed 43 transactions in each interval
• a large GraphQL query being allowed only 3 transactions in each interval

It’s important that both the API Developer and the API Consumer can easily understand these rate limits, as they edit their GraphQL query.

Visibility

We always had REST and SOAP APIs with various endpoints which were visible in gold or platinum plans and hidden in public or free plans. Here’s a picture of configuring visibility in a REST or SOAP API:

While GraphQL opens up the visibility of the server’s capabilities dramatically, the paradigm isn’t different. Every API Plan constrains the REST, SOAP, and GraphQL abilities of its APIs, and advertises them appropriately in the Developer Portal. In the case of GraphQL, this means limiting not only which top-level queries are available but also fine-grained control of types and fields within the queries.

These settings then yield an experience for the API consumer that you saw earlier in this post when we tried out the Simple Mobile Banking Application’s subscription to the Silver Plan.

It’s much more powerful and fine-grained than the control you have over visibility of REST APIs, but it’s conceptually the same idea of restricting API visibility in API Plans based on which plan the API consumer is choosing to buy. As with other features, it should naturally extend the abilities you already had for REST and SOAP, in the same places in the API Manager and Developer portal, but optimized for the GraphQL experience.

Summary

It’s really all about “First Class Support” of GraphQL, by having API Management allow your GraphQL APIs to play in all the same ways that your REST APIs always did. The hardest parts are where providing the same feature in the same place requires a new mechanism, such as GraphQL Cost Rate Limiting. Even with these more complicated features, it really comes down to consistently providing the same functionality that you used to, and in the same place.

Let’s recap: What’s the most important thing you need as you start adding GraphQL APIs into the API Management mix?

Consistency.