Querying All Appwrite Developers - GraphQL Has Arrived
Tags: graphql, api, webdev, appwrite
Published: 2022-12-28 08:46:35

Hot on the heels of two huge releases comes Appwrite 1.2, bringing with it a brand new, highly anticipated service: GraphQL. 

Our vision for Appwrite is always to meet developers where they are. Build relying on your knowledge, stack of choice, or preferred APIs. 

Today, we take another step in following this vision. We’re happy to introduce an **experimental GraphQL API**. A new way to integrate with Appwrite and use all the services you already know and love.

In addition to a new API comes a GraphQL explorer, upgraded SDKs, and improvements to the documentation.

## GraphQL API

[GraphQL](https://graphql.org/learn/) is a powerful technology that allows developers to easily and efficiently access data from an API. It provides a flexible and intuitive query language that makes it easy to retrieve exactly the data that an application needs. This eliminates the need for multiple round trips to the server and can reduce the amount of data that needs to be transferred, resulting in faster and more efficient applications. 

The Appwrite GraphQL API offers full support for all of Appwrite’s services. This means you can manage your accounts, databases, storage, functions, and more, all via GraphQL queries and mutations.

The GraphQL API is exposed on the route `/v1/graphql`, all queries and mutations should be sent to this route as JSON, following the [GraphQL HTTP request model](https://graphql.org/learn/serving-over-http/):

```json
{
  "query": "...",
  "operaiontName": "...",
  "variables": {},
}
```

The `query` key should contain the query or mutation you want to execute. `operationName` and `variables` are optional fields. `operationName` should only be included if there are multiple operations in the `query.`

A mutation to create an account could like this:

```graphql
mutation {
  accountCreate(
    userId: "unique()"
    email: "team@appwrite.io"
    password: "Team.Appwrite.IO"
  ) {
    _id
    _createdAt
    status
    email
  }
```

To use variables, and allow re-using a query, the mutation could look like this:

```graphql
mutation AccountCreate($userId: String!, $email: String!, $password: String!) {
  accountCreate(
    userId: $userId
    email: $email
    password: $password
  ) {
    _id
    _createdAt
    status
    email
  }
```

With this mutation, the `variables` parameter also needs to be passed in the request, to fill in the values for `userId`, `email` and `password`:

```json
{
  "userId": "unique()",
  "email": "team@appwrite.io",
  "password": "Team.Appwrite.IO"
}
```

The mutation is now able to be used across multiple requests, all that would need to be changed are the values of the variables.

## GraphQL Explorer

Appwrite GraphQL Explorer is a powerful tool for working with the new GraphQL API. Based on the Altair GraphQL client, it has a user-friendly interface that makes it easy to explore the GraphQL API, even for those new to the technology. It supports all the features of GraphQL, including query variables, fragments, and custom headers, which makes it a very versatile tool.

![GraphQL Explorer Screenshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/clonjhdvb62n9357scc3.png)

You can find the instructions to run the GraphQL explorer in this [Gist](https://gist.github.com/stnguyen90/8b6b80682d80cfec130a61e60e07d1f9#file-start-appwrite-graphql-explorer-sh-L3).
 
Some extra features make it even easier and more enjoyable to use:
- Searchable documentation
- One-click query generation from documentation
- Intelligent auto-complete and error highlighting for queries
- Support for multiple tabs and environments

## SDK Updates

The Appwrite SDKs have all been updated to support the GraphQL API by including a new service of their own. This can be used to interact with the API in the same way as other SDK services:

```js
import { Client, GraphQL } from "appwrite";

const client = new Client()
   .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your Appwrite Endpoint
   .setProject('[PROJECT_ID]');            	// Your project ID

const graphql = new GraphQL(client);

const mutation = graphql.mutation({
   query: `mutation {
   	accountCreate(
       	userId: "unique()",
       	email: "team@appwrite.io,
       	password: "Team.Appwrite.IO"
   	) {
       	_id
       	email
   	}
   }`
});

mutation.then(response => {
   console.log(response);
}).catch(error => {
   console.log(error);
});
```

This makes it possible to take advantage of GraphQL regardless of your preferred language or application platform.

Appwrite is agnostic when it comes to client support; this means any other GraphQL client can be freely used for those comfortable with a different product.

## Documentation

To keep Appwrite as easy to use as possible as new APIs are added - the documentation underwent an upgrade. There are now dedicated quick-start guides for [REST](https://appwrite.io/docs/rest), [GraphQL](https://appwrite.io/docs/graphql) and [Realtime](https://appwrite.io/docs/realtime), making it easier to get started with any of the available APIs.

![Documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/05vggef5ltiputes4r21.png)

To complement this expansion, there are now examples of REST requests and GraphQL queries for all services, so it is easy to see how to interact with Appwrite even if communicating directly over HTTP instead of via one of the many SDKs.

## And More

Appwrite 1.2 includes other changes. Check out the changelog [here](https://github.com/appwrite/appwrite/blob/master/CHANGES.md) for the full list of new features, bugs fixed and other changes.

## Try It Now

We are super excited about releasing the GraphQL API, GraphQL Explorer, and SDK support. This update provides another powerful and intuitive way to access and manipulate Appwrite, and we hope it will greatly improve the developer experience. We encourage all developers to upgrade to this new version and take advantage of the new features. Thank you for your continued support, and we look forward to any feedback.

## Learn more

You can use the following resources to learn more and get help:

- 🚀 [Appwrite Github](https://github.com/appwrite/appwrite)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
- 💬 [Discord Community](https://appwrite.io/discord)