Expose your data from Azure Cosmos DB or Azure SQL through a GraphQL API with Azure API Management

Today, we’re announcing the public preview of two GraphQL resolver types for Synthetic GraphQL in Azure API Management: Azure Cosmos DB and Azure SQL resolvers. If you ever faced the challenge of exposing your database through GraphQL, you’re aware of the complexities involved. It typically involves writing numerous lines of code, dealing with resolvers, and figuring out the nuances of database access. But is there a simpler way? 

Enter Azure Cosmos DB and Azure SQL data types in Synthetic GraphQL for Azure API Management. Upload your GraphQL schema and expose desired data using familiar database concepts – a seamless and straightforward process. In this blog post, I will walk you through the process of adding a GraphQL resolver for a Cosmos DB backend and demonstrate how to test it. 

An example: The To-do List Demo 

Let’s look at the to-do list application as an example. Every to-do item has an id, title, and status. I already have some of the items in Azure Cosmos DB, which has the following structure, and want to enable a list of simple CRUD operations on it. 

{ 
    "id": "1", 
    "title": "Test1", 
    "completed": false 
} 

Create a GraphQL Schema and a Synthetic GraphQL API

I can model this to-do item application by creating the following GraphQL schema:

type TodoItem { 
  id: ID! 
  title: String! 
  completed: Boolean! 
} 

input CreateTodoItemInput { 
    id: ID! 
    title: String! 
    completed: Boolean! 
} 

input ReplaceTodoItemInput { 
  id: ID! 
  title: String! 
  completed: Boolean! 
} 

type Query { 
  todoItems: [TodoItem] 
  todoItem(id: ID!): TodoItem 
} 

type Mutation { 
  createTodoItem(input: CreateTodoItemInput!): TodoItem! 
  replaceTodoItem(input: ReplaceTodoItemInput!): TodoItem! 
  deleteTodoItem(id: ID!): Boolean 
} 

To create this GraphQL API within the Azure API Management service: 

• Open the Azure portal in your browser 
• Select your existing Azure API Management service (or create a new one) 
• Select the APIs blade 
• Select GraphQL to create a new GraphQL API 
• Fill in the form: 
  • Choose a Display name (Todo-GraphQL) 
  • The name field will auto-fill with a suitable name 
  • Select Synthetic GraphQL 
  • Select the file that contains the GraphQL Schema 
  • Choose an API URL suffix (todogql) 

• Select Create to create the API

Create a resolver 

With the addition of Azure Cosmos DB and Azure SQL, you can now select what data source you want to use when you’re configuring your resolvers – HTTP API, Azure SQL or Azure Cosmos DB. Let’s create a Cosmos DB resolver for a 'todoItem' query: 

• Select the Resolvers tab and then select + Create 
  • Set the name for a resolver, type, and field to target for this resolver 
  • Select a data source type you want to use – Azure Cosmos DB 

When you choose a specific data source, the resolver policy editor gets a pre-populated XML document that defines how to query a database and retrieve the data we need. For the todoItem query I need to get an element by ID, so I create the following policy: 

<cosmosdb-data-source> 
    <connection-info> 
        <connection-string>”replace-cosmos-db-connection-string”</connection-string> 
        <database-name>tododemo</database-name> 
        <container-name>todo</container-name> 
    </connection-info> 
    <read-request> 
        <id>@(context.GraphQL.Arguments["id"].ToString())</id> 
        <partition-key>@(context.GraphQL.Arguments["id"].ToString())</partition-key> 
    </read-request> 
</cosmosdb-data-source> 

Note: For simplicity, I put a connection string directly into the policy. However, you should not store secrets as plain text. Instead, you should use Named Values connected to a secret in a Key Vault.

This is a relatively simple resolver. I specified my connection information for an Azure Cosmos DB including connection string, database name and a container name. In the following <read-request> section I take an id argument from the GraphQL request context and use it to perform a query against the database. You can use read, write, and delete requests, which hide some of the complexity of interacting with the database, but you can also write your own queries with the <query-request /> policy section. 

Test the API 

Now when I uploaded the schema and created a resolver for a query, I can test it in a built-in GraphQL test console: 

• Select the Test tab 
• Modify the GraphQL query 
• Select Send to send a request 

Having successfully obtained the necessary data from Azure Cosmos DB using a GraphQL API, we can now generate additional resolvers – one for each query and mutation following the same process that we used before. Check out the documentation for more information. 

Next steps 

Azure Cosmos DB and Azure SQL resolvers are in public preview, give it a try and let us know what you think in the comments below!