GraphQL Queries

A GraphQL query retrieves data from a server, similar to a GET request for a REST API. However, unlike REST, all GraphQL queries are sent to a single endpoint and use the POST method.

A GraphQL API models data as nodes connected by edges. A node is an object that has a global ID (in Zencargo we use UUID for that purpose), such as a Purchase Order object or Product object. You can fetch data about an individual node, or you can fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.

QueryRoot

The QueryRoot represents easily accessible entry points into the GraphQL API. Everything that can be queried is defined as a field or connection on the QueryRoot object.

The following query requests the account object, some field on that object, and the products connection in a single request.

POST /graphql
Query

query {
  account(uuid: "a7353774-9795-434b-a1f8-7582b6afd345") {
    uuid
  }
  products {
    nodes {
      id
      name
      skuCode
    }
  }
}

JSON Response

{
  "data": {
    "account": {
      "uuid": "a7353774-9795-434b-a1f8-7582b6afd345"
    },
    "products": {
      "nodes": [
        {
          "id": "a16e4969-9d32-4ff6-b704-6429ac523c34",
          "name": "Bed",
          "skuCode": "SKUAX001"
        },
        {
          "id": "353a810a-7a2e-4caa-b7b5-82078ad6faec",
          "name": "Chair",
          "skuCode": "SKUAX002"
        },
        # ...
      ]
    }
  }
}

Filtering connections

You can filter connections by using available arguments to return only nodes that match that search argument. To learn which fields you can filter a connection by, refer to the API documentation for the connection's arguments.

The following query finds the first two products whose name contains the word chair.

POST /graphql
Query

query {
  products(first: 2, nameContains: "chair") {
    nodes {
      id
      name
      skuCode
    }
  }
}

JSON Response

{
  "data": {
    "products": {
      "nodes": [
        {
          "id": "a16e4969-9d32-4ff6-b704-6429ac523c34",
          "name": "Aerodynamic Chair",
          "skuCode": "AC-1234"
        },
        {
          "id": "353a810a-7a2e-4caa-b7b5-82078ad6faec",
          "name": "Wool Chair",
          "skuCode": "WC-4567"
        }
      ]
    }
  }
}

Next Steps