• Introduction to GraphQL
  • GraphQL API
  • For Developers

    • Introduction to GraphQL

    In this article:

      Attention   

       

      What is GraphQL?

      GraphQL is a query language and a runtime system. Clients form requests (called queries and mutations) by using the GraphQL query language, and the GraphQL server executes the request and returns the data in a response.

      A client specifies exactly the data that it wants, and the server responds with only that data.

      GraphQL looks similar to JSON. The following example shows a simple GraphQL query and the JSON response:

       

      POST shop99999.mywebshop.io/api/graphql
      (Replace "shop99999" with your own shop number)

       

      

query {
  orders {
    data {
      id
      languageISO
      siteId
      orderComment
    }
  }
}

      Response

      

{
  "data": {
    "orders": {
      "data": [
        {
          "id": "1",
          "languageISO": "DK",
          "siteId": "1",
          "orderComment": null,
        }
      ]
    }
  }
}

       

       

      When you ignore the top-level data key in the JSON response, the structure of the keys in the response is the same as the structure of the GraphQL request.

       

      What are the benefits of using GraphQL instead of REST?

      GraphQL addresses several problems that might sound familiar to anyone who’s worked with a REST API.

      REST | Fetching associated data often requires multiple HTTP calls

      REST APIs are built on the principle that every endpoint should return only one type of resource. For example, the request GET api.{shop_domain}/admin/products/1 retrieves the information for product 1, but nothing more. This means that if you want a product's variants, images, and metafields, then you need to make at least four HTTP calls.

      REST | Apps receive more data than they need

      To solve the above problem, we end up breaking away from true REST APIs by embedding certain associations to certain end-points when the need arises. For instance, GET /products/1 returns information about the product, but also its variants, images, and options. Ultimately we end up with one-size-fits-all responses where you cannot request less nor more than what we give you.

      REST | Dandomain Webshop doesn't know what data an app is using

      When an app requests a REST endpoint, Dandomain Webshop has no way of knowing if it's actually using every piece of data that's returned. It’s similar to doing a SELECT * to a SQL database. This is problematic because when Dandomain Webshop needs to make breaking changes, such as remove an attribute from a response, it’s nearly impossible to know who it will affect. We know which clients call which endpoint, but we don’t know what subset of those clients are using the attribute that we're removing. Some attributes are also costly to compute. If we knew that the app doesn’t need a costly attribute, then we wouldn’t need to compute it in the first place.

      REST | REST APIs are usually weakly-typed and lack machine-readable metadata

      While there exists some solutions to the problem of not knowing which data is being used (like JSON Schema), the reality is that most REST APIs do not provide this sort of metadata. The result is that apps rely on documentation, which can become out of date or might be incomplete.

      GRAPHQL | Everything is typed and part of a schema

      Everything that's available through a GraphQL API is included in its schema. You can use the schema to build queries that return only the data that you need. This solves the problem of over-fetching data. It also means that we know which fields each app is using, making it easier for us to evolve our APIs over time.

      GRAPHQL | Everything is available from a single endpoint

      All GraphQL requests are sent to the shop99999.mywebshop.io/api/graphql endpoint (Replace "shop99999" with your own shop number), which means that you can often retrieve all the data that you need in a single request. Using GraphQL features such as variables, and aliases, you can make your queries incredibly efficient and retrieve data about many resource types in a single request.

      GRAPHQL | Documentation is a first-class citizen

      The documentation for a GraphQL API lives side-by-side with the code that constitutes it. Combined with the typed schema, this means that we can generate accurate and up-to-date documentation whenever something changes. Using GraphQL's introspection feature, you can query the schema itself to explore its contents and documentation.

      GRAPHQL | Deprecation is a first-class citizen

      We can easily mark a part of our schema as deprecated, and this will also be reflected in documentation. GraphQL tooling, such as client libraries, is also expected to communicate to the developer that they're using a deprecated tool.