Intro
A more convenient way to fetch data from API's
- Instead of 'GET'ing a resource you 'POST' a query that describes what data you want.
- You think of the data your API returns as a "graph", this allows you to make queries to fetch "related" pieces of data in a single shot. In the example above, you fetch the user and the user's address (as a nested JSON object) in the same API call, as opposed to making 2 API calls.
- The "query" you send as data in the POST request has a structure and a syntax. This "language" is called GraphQL.
Example Query
query { | {
user (id: 1) { | "user": {
id | "id": 1
name | "name": "Elmo"
} | }
}
Benefits
- Avoid overfetching as specify exactly what data is required
- Single API calls
- No need for new API's to be made
GraphQL client-server flow
- Note that the GraphQL query is not really JSON; it looks like the shape of the JSON you want. So when we make a 'POST' request to send our GraphQL query to the server, it is sent as a "string" by the client.
- The server gets the JSON object and extracts the query string. As per the GraphQL syntax and the graph data model (GraphQL schema), the server processes and validates the GraphQL query.
- Just like a typical API server, the GraphQL API server then makes calls to a database or other services to fetch the data that the client requested.
- The server then takes the data and returns it to the client in a JSON object.
Fetching data
Sample query
query {
users {
name
todos {
title
}
}
}
Sample query with arguments
query {
todos(limit: 10) {
id
title
}
}
query {
users (limit: 1) {
id
name
todos(order_by: {created_at: desc}, limit: 5) {
id
title
}
}
}
variables
query ($limit: Int!) {
todos(limit: $limit) {
id
title
}
}
{
"limit": 10
}
Writing data
Mutation
mutation {
insert_todos(objects: [{title: "new todo"}]) {
returning {
id
}
}
}
mutation($todo: todos_insert_input!){
insert_todos(objects: [$todo]) {
returning {
id
}
}
}
{
"todo": {
"title": "A new dynamic todo"
}
}
Subscription
GraphQL subscriptions are a way of adding realtime or reactive features to an apps. GraphQL clients and servers that support subscriptions are great because they allow you to build great experiences without having to deal with websocket code!
GraphQL queries/mutations are strings sent to a POST endpoint. A subscription can't happen over a POST endpoint, because a simple HTTP endpoint would just return the response and clsoe the connection.
A GraphQL subscription is a subscription query string sent to a websocket endpoint. And whenever data changes on the backend, new data is pushed over websockets from the server to the client.
subscription {
online_users {
id
last_seen
user {
name
}
}
}