Understand GraphQL

Introduction#

The Wino's GraphQL API was built with GraphQL. If you're not familiar with this kind of APIs, it's recommended to make some research about GraphQL before.

First of all, a little introduction to this technology. What is GraphQL?

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data. — graphql.org

Unlike REST APIs, which expose a different endpoint for each resource object, a GraphQL API makes all data available at a single endpoint /graphql. A client specifies exactly the data that it wants, and the server responds with only that data.

The following example shows a simple GraphQL query and the JSON response:

REQUEST /graphql

query {
  product(id: "d9c97946-bab9-11ea-b3de-0242ac130004") {
    name
    kind
    color
  }
}

RESPONSE /graphql

{
  "data": {
    "product": {
      "name": "Petrolette 5°",
      "kind": "BEER",
      "color": "BLOND"
    }
  }
}

You can try it now on our Playground (soon). Or in any other third platform.

Benefits of using GraphQL#

GraphQL's declarative approach to data fetching provides significant performance and quality-of-life improvements over a REST API:

Everything is typed and part of a schema
Data fetching is declarative and efficient
Everything is available from a single endpoint
Documentation is a first-class citizen

Make queries#

The schema's entry-point for queries. This acts as the public, top-level API from which all queries must start. In this API, it is possible to search for one instance or an array of instances of any schema.

Request a single record from a collection#

To retrieve an item, you must add its unique identifier ID! to the query variables. Here is an example of retrieving a Node from the Product collection:

REQUEST /graphql

GraphQL
JavaScript
PHP

query {
  product(id: "d9c97946-bab9-11ea-b3de-0242ac130004") {
    name
    kind
    color
  }
}

RESPONSE /graphql

{
  "data": {
    "product": {
      "name": "Petrolette 5°",
      "kind": "BEER",
      "color": "BLOND"
    }
  }
}

To know the fields associated with a particular collection, for example Product, you can refer to GraphQL Reference.

Request a complete collection#

To retrieve the elements of a collection, you must use the Connection pattern as follows:

REQUEST /graphql

GraphQL
JavaScript
PHP

query {
  products {
    edges {
      node {
        id
        name
      }
    }
  }
}

RESPONSE /graphql

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "d9c97946-bab9-11ea-b3de-0242ac130004",
            "name": "Petrolette 5°"
          }
        },
        {
          "node": {
            "id": "6464d97b-e9db-486b-8c32-ddb71494f79d ",
            "name": "Old Ballantruan"
          }
        }
      ]
    }
  }
}

By default, a maximum of 20 nodes can be retrieved per request. If you want to retrieve more items from a collection, you can use the first argument as described in the Connection type. To manage pagination, you can refer to the dedicated guide Paginate data.

Accessing resources layers in a single request#

This query requests informations about others relationships in a single request: VariantPrice, Category, Variant, Tax etc. with the exact data you want.

REQUEST /graphql

GraphQL
JavaScript
PHP

query {
  variant(id: "96835dcb-6dbc-4a44-ac94-3cfae1293eec") {
    name
    product {
      name
      tax {
        value
      }
      category {
        formattedName
      }
    }
    variantPrices {
      edges {
        node {
          valueIncludintTax
          price {
            name
          }
        }
      }
    }
  }
}

RESPONSE /graphql

{
  "data": {
    "variant": {
      "name": "2017, 0.75cL",
      "product": {
        "name": "Crozes Hermitage",
        "tax": {
          "value": 20
        },
        "category": {
          "formattedName": "Vins > Rouge"
        },
        "variantPrices": {
          "edges": [
            {
              "node": {
                "valueIncludingTax": 14.0,
                "price": {
                  "name": "Tarif Boutique"
                }
              }
            },
            {
              "node": {
                "valueIncludingTax": 13.8,
                "price": {
                  "name": "Tarif Ecommerce"
                }
              }
            }
          ]
        }
      }
    }
  }
}

The way GraphQL works will be detailed in the other documentation guides.

Mutation#

The root Mutation type in a GraphQL schema defines all the write operations that can change data. It is analogous to performing HTTP verbs such as POST, PATCH, and DELETE.

Mutations can take arguments as input similar to the body of a POST request in REST. Like GraphQL queries, mutations can also return fields. This can be useful for fetching the new state of an object after an update.

Playground#

The Playground is a way for you to interact with the Wino API. This will allow you to very easily test and understand the database entries through integrated documentation and auto-completion.

More information about the Playground can be found here .

External ressources#

If you wish to have more precision on the use of a GraphQL API, you can refer to the guide proposed by Github "Forming Calls with GraphQL".