API management for GraphQL?

Published in

APIOps

6 min readSep 4, 2018

GraphQL is the newer kid on the block and eats APIs for breakfast or even replaces the need for them — or does it? That’s what we gathered to investigate and discuss in 08/2018 APIOps Helsinki meetup. My talk and demos using Apollo and Apollo Engine compared to some REST API management tools concentrated on API management functionality and it’s requirements on API / GraphQL design while Mikhail Novikov from GraphQL Finland was giving an introduction on GraphQL.

APIOps Helsinki 08/2018 at Microsoft Flux

There were a lot of questions going on. Many front-end developers dote on GraphQL but why should others care? What’s in it for software architects? What about back-end developers, integration people, API management enthusiasts and the lot. But what we really concentrated on was How is managing GraphQL different to REST APIs or is it? What is their relationship?

Many enterprises are still jumping on the REST bandwagon. There are some clear benefits to GraphQL compared to REST APIs. -Even more so with badly-designed REST APIS. But even if the REST APIs are well-designed, you might find GraphQL useful. It might be you have a lot of different use cases. Or different devices for using the APIs. These might cause many different versions of the API for different clients.

Consider even your analytics tools as a different client. It will need summarized data. Your online shopping applications will need transactional (and sometimes also summarized data). While your desktop users can fit 20+ columns of data to their screens, your mobile applications might choke. This could happen even if you load those 20+ columns and only show 2 of them, which fit the screen.

Alarm bells sound in the minds of IT application, capacity and network managers when someone makes the point that GraphQL can work together with REST APIs. Worse, they can query and combine multiple REST API calls to one query. Doesn’t this mean that the network and back-end traffic are going to be enormous? And that there are security leaks all over the place? What about updating the data? Or handling files?

Not to mention access control on who can see or use your APIs? Rate limits? Documentation or monetization? CIOs, IT managers and integration platform owners have read their share on Gartner reports. And downloaded whitepapers from Mulesoft, IBM etc. Some may even have joined my trainings or read our book on API Economy. All have told them about something called “API management”.

For REST APIs, API management is not new. It is at least in adoption phase in a growing number of organizations, as a process and as tooling. But for GraphQL, it’s quite a new thing. The tools used for REST APIs (not to mention SOAP web services) are not built for this purpose.

For many front-end, back-end and integration developers, even the REST API management is hazy. What does it include, what does it mean regarding the design of APIs? And more to the point, is it really needed now? Can’t we just jump directly to GraphQL or just offer simple APIs generated from database or something if we are going to put “GraphQL icing” on top of them?

Front-end developers working mainly with GraphQL often get caught with many of the design issues that already applied to REST APIs. And if there is a REST API back-end for the GraphQL server to use, then you either patch bad REST things up in GraphQL or you risk doing all the design failures (again) in GraphQL which you might have had or avoided in REST.

Some baselines on REST APIs, which won’t go wasted even if you put GraphQL on top of them:

• Use OpenAPI (previously Swagger) -definitions for your API. OpenAPI 3.0 starts to be quite well supported already in tooling.

Use API management-process and tooling
Use OpenID Connect (not API keys, not just OAuth). Use also token-based claims for access management. This is important for personal or otherwise sensitive data, but also if your API has multiple users like partners or customers who should only access their own data.
Design according to customer need, efficiency and best practices, don’t go too general purpose but don’t design just for one application. Consider making your API endpoints query friendly and limiting the number of returned attributes etc.
Do not change your APIs version number (if any) unless there is a major change which is not backward compatible. Choose a versioning strategy that matches your API management tooling.
Be safe enough, don’t go overboard if your GraphQL and REST APIs deal only with what is already in the public internet. But still remember that if you expose an endpoint to open web without any authentication you risk others starting to use it even if it’s not an actual security risk. Even for public data use normal security measures you would for a website but also authentication.
Use HTTP status codes wisely, remember that there is more than 200 ok, 4xx for “it’s your fault” as a consumer and 5xx for “it’s my fault” as a provider.
Read full check list here

Bridge from REST to GraphQL

OpenAPI to GraphQL automatic conversion can be done, with tools like https://github.com/yarax/swagger-to-graphql but those should only be used as a starting point.
Remember that poor REST design makes poor GraphQL endpoint
(Re-)think about your error codes and design, remember that GraphQL doesn’t really work with only the HTTP status codes. When is it wrong to return partial data and what should the response code be then? Or should you remove errors from the response or mark them as errors?
Trusting your underlying REST APIs to handle security of your GraphQL is complex: you definitely can’t rely on GraphQL server alone but being able to combine data in your queries on a whim may bring whole new compliance and security issues. Also client security, specially mobile, single-page-app or other client running on “insecure” devices should be thought carefully and also GraphQL endpoint and traffic should be secured (or all request should go to backend which would handle all security, but that might destroy your caching strategy).
Metrics and monitoring should be in place for GraphQL endpoints too, for debugging, auditing and possibly even monetizing the usage.

Role of API management

What does API management include as a technology:

Typical minimum features include

• Proxy

• Gateway between different network environments

• Authentication of API calls

• Throttling per API

• API subscription management

• Analytics of API calls

• Versioning APIs and transitioning consumers, managing API lifecycle

• Documentation (executable/testable/partly automatically generated), code snippet generation

Some additional features you might need depending on the developer experience you want to offer:

• Providing specification files to consumers

• Productizion: subscription plans & rate limits, naming, support

• Monetization

• Community management, communications with API consumers and non-developers needing information on the APIs

What about GraphQL endpoint management, then?

Currently GraphQL servers are available from Apollo (Apollo Engine) and AWS AppSync and they do some of the things a REST API management platform or tooling would do. You might want to give Apollo server and the new member of the family Apollo Engine a try and you will get some of the “minimum” features listed above for API management. Specially documentation and analytics.