Modernize your API Stack with GraphQL and Azure API Management

Introduction

In this article from our series from INTEGRATE 2022, Let's take a deep dive into the session on how to modernize your API stack with GraphQL using Azure API Management, as presented by Elizabeth Barnitt, a Program Manager in Microsoft for API Management.

Elizabeth started her session with a bunch of product updates, including some features available in Public Preview.

• Authorizations: Managed Token Store and Token Mapping for OAuth2-Secured backends.
• Private Link Integration: Simple to set up secure inbound connectivity to API Gateways available in all-tier except consumption one.
• Managed Certificate Support: Easily and quickly secure custom domains with free certificates automatically provisioned and renewed by API Management.
• Synthetic GraphQL APIs: Easily create a GraphQL API based on your existing HTTP (SOPA or REST) APIs.

The following features are generally available with Azure API Management:

• SOAP and XML request and response validation.
• Validate Content Policy now support SOAP and XML-based Payload.
• Schemas can now define as additional, service-level resources.
• Event Grid Integration.
• Subscribe to events from API Management in Event Grid to Automate workflows and process.
• Self-Hosted Gateway V2.
• Unified codebase, support for open Telemetry, new configuration endpoint.
• WebSocket APIs.
• Publish and mediate existing WebSocket APIs in API Management.
• Developer Portal.
• Inject custom HTML code into Managed Portal with the new widget.
• Improved OpenAPI support in API reference pages and revised code samples.
• Policy Fragments.
• Define complex policies once and re-use them anywhere.
• Power Platform Integration.
• Export APIs as custom connectors for use in Power Apps and Automated Flows.
• GraphQL APIs.
• Publish and mediate existing GraphQL APIs in API Management.



Why GraphQL?

REST APIs have been with us for many years now. In that time, our expectations of client applications have grown. We expect client applications to run on mobile devices with low bandwidth, yet still, be responsive. Unfortunately, REST APIs restrict us in three basic ways:

• It takes too many requests to fulfil the data needs for a single page.
• The REST API returns too much data for the page being rendered.
• The client application needs to poll to get new information.

Elizabeth showed a sample scenario with a Microsoft Store Page, which seemed relatively simple, but when analysed further, you realize you need to make so many REST calls to load this page. This is a major problem for all modern-day applications.

There have been various attempts to solve these issues, and the current favourite is GraphQL. GraphQL is a protocol specification that explicitly solves these issues. The client application can specify the data they need to render a page in a query document that is sent as a single request to the GraphQL service. A client application can also subscribe to changes in the data through a real-time WebSocket connection, allowing notifications to happen in a timely manner.

What is GraphQL?

• A query language for your API.
• GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.
• A single call to a single endpoint.
• GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
• Helps to optimize the network bandwidth and reduces the number of calls to different API endpoints for different information Authorization Extremely secure, Instead of endpoint level authorization you can authorize at field level.




Going back to the same example, but now with GraphQL, you can see that you are just running a single query to a single endpoint, and still get all of the data that’s needed to render the page.




Why do developers love GraphQL?

• Introspection.
• This allows developers to discover the resources available to them in the GraphQL Schema. Developers can explore the schema, they can learn about different fields, queries and types.

This makes it easy for developers to onboard, explore and build on top of the existing queries that they are using.

• Auto Backward Compatibility.
• The front end will not be broken when API gets updated. Rather than changing the endpoint itself and breaking the existing calls, it is much more focused on not making breaking changes by not changing the existing queries but rather adding new required queries.
• Client Generation.
• Helps to send test queries via clients like Graphical or Insomnia.
• Self-Documenting.
• All the queries, subscriptions, and types are automatically documented in the GraphQL Schema and when you generate a client this can be explored by developers.
• Real-time updates.
• It does support real-time updates, for example whenever query results change server can return new results to the client.

How do I implement GraphQL?

Elizabeth also touched upon how can you get started with implementing GraphQL.

• GraphQL Server.
• Create a GraphQL Server using a tool like Apollo Server and create your schema and resources.
• Combine REST endpoints.
• Aggregate multiple REST endpoints to Single Endpoint, by creating GraphQL Schema and mapping those endpoints' responses to GraphQL Schema resources so that data get served.
• GraphQL Server + Augmentation.
• This is the combination of the first two options, relying on the existing GraphQL Server and extending the information from another REST point by attaching them to GraphQL Schema and resolving those using resolvers when queries get called for data.



Steps to Build GraphQL


• Start with a Schema: It outlines different types, resources and how information gets processed
• Define Resolvers: It helps to map the types and fields to the source of the information it can serve to. For example what endpoints or APIs serve the request?
• Link resolvers to data sources: The actual implementation to link defined resolvers to the data sources.



GraphQL in Azure API Management




GraphQL Pass-through

There are two ways to implement GraphQL via Azure APIM.




You can use this when you already have an existing GraphQL API, which then you can plug in thru Azure APIM, leveraging all the existing benefits of API Management—including security, observability, and reduced latency—for their GraphQL APIs while also adding GraphQL-specific features such as a query test console, query validation, field-based authorization, and query depth and size restriction.




Synthetic GraphQL



With this second approach, Synthetic GraphQL allows you to easily create a GraphQL API based on your existing HTTP (SOAP or REST) APIs. This allows you to quickly upgrade your API to support modern client application development without affecting your existing infrastructure.

• With this availability, you can:
• Change your existing APIs into GraphQL to support modern client application development. Build a GraphQL API from existing SOAP, REST, and other HTTP APIs.
• Augment your existing GraphQL API with third-party APIs such as Microsoft Graph, Dynamics, Shopify, and Zendesk.
• Build your GraphQL API.



With the preview GraphQL resolvers, you can remove the GraphQL backend completely and define a complete set of resolvers to fulfil any query. The resolvers can easily be written in Azure Functions or take advantage of REST APIs across M365, Azure, your own services, or third-party services such as Shopify, Marketo, or ServiceNow. The Synthetic GraphQL service will run all the required requests and combine the results into the response to the user.

After explaining the Synthetic GraphQL on Azure APIM, Elizabeth ran through a really cool demo using SpaceX GraphQL APIs and Azure APIM. She also demonstrated how convenient it is to extend the existing GraphQL with additional HTTP requests.




API Management protects against the top 5 OWASP GraphQL security issues

Briefly, the top 5 security issues with GraphQL were discussed and she also showed how those issues can be mitigated with Azure APIM.





Key Takeaways / Cluster Take

1. Use GraphQL to extend the features without losing your backend APIs investments.
2. Production GraphQL is easier and more secure with Azure API Management.
3. Looking back at Toon Vanhoutte's session on APIM, he mentioned the Layered API pattern with an Experience layer that customises lower-level APIs for specific audiences and clients. Rather than hand-rolling these APIs, we can see great opportunities for organisations to leverage the newly-announced Synthetic GraphQL features of Azure APIM to build on existing investment in REST and SOAP APIs and expose a flexible single endpoint to API clients. Synthetic GraphQL APIs will allow API clients to query APIs in a self-service manner to retrieve just the data they need, all without compromising on governance or data security.



If you would like to schedule a workshop to learn more about how you can leverage the Azure APIM to connect with your existing APIs and build a GraphQL on top of them, please reach out to us via our LinkedIn Page or email us at and we will be happy to guide you on your journey to Azure Adoption.





Useful Links

• Import a GraphQL API
• Import a GraphQL schema and set up field resolvers
• Transform your REST APIs into GraphQL with Azure API Management
• How to use a GraphQL on Azure