Make your first GraphQL request

This guide describes the basic steps for getting started with Zencargo's GraphQL API and submitting your first request.

Setup

Note: Before we get started make sure you have a Zencargo account and you've followed the steps described here

Using an API client

After you have setup an account and a have a set of API credentials, you need a way to make requests to the API. You can choose your API client of choice, as all we'll be doing in this guide is showing a simple example request. Some options are:

Zencargo's API Console

Once you are familiar with GraphQL, the API Console allows you to make GraphQL requests and see the responses within the context of your own account. This is the preferred method for learning and exploring Zencargo's GraphQL APIs in detail because the console provides many features, such as auto-complete and API documentation.

Standalone HTTP clients

You can use any standalone application that can perform HTTP requests to interact with the API. These are excellent testing tools because they allow you to configure multiple environments, allowing you to switch between your staging/test and production accounts with ease. Postman is a popular choice.

cURL

cURL is the easiest way to illustrate the makeup of a GraphQL request because you can make requests directly from your terminal without downloading any extra software. We'll use this as our tool in this guide. You almost certainly already have it installed, but be sure that you can run curl from your terminal before proceeding.

Making our first request

We'll now try to make our first request, to get some Product SKU codes from your account, utilising the credentials we generated in the previous guides. Make sure you have the following variables to hand:

The makeup of the cURL request

Here's how cURL requests need to be formatted to correctly query Zencargo's API.

curl -X POST \
  https://{ accountRef }.api.{ environment }.zencargo.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic { api_credentials }' \
  -d ' { "query": "query { products { nodes { name skuCode } } }" }'

The URL

As a reminder, all requests to our GraphQL API are POST requests to the same endpoint. This is one of the major differences to a REST API. You do not need to define a resource or operation in the url (it is defined in our -d parameter).

The Headers

The headers should be fairly self-explanatory (remember to insert your credentials after following the authentication guide).

The Data

The final line defines the data that's being sent along with the request. Because we handle all requests to our API using POST requests, you have to define the operation and its type in the data of the request, as a string that adheres to the GraphQL schema. In this case, it's a simple query to retrieve all nodes of the Product object, specifically their skuCode attribute.

In our API guides, we include sample payloads. For brevity, we omit most of the structure of the HTTP request and instead only specify the contents of the data of the request.

If we were to write the above query using GraphQL syntax in our guides, it would look like this

POST /graphql
Query

query {
  products {
    nodes {
      skuCode
    }
  }
}

In our cURL request, this becomes:

-d ' { "query": "query { products { nodes { skuCode } } }" }'

You should immediately be able to spot that the string we sent in the HTTP request was nothing more than our GraphQL syntax encoded inside a JSON object, under the property "query". You can learn more about the specifics of this JSON object in later guides, but it's important to keep this formatting in mind - especially when you come to use variables which will require you to include a second property, "variables" in the JSON object.

To save yourself time when playing around, you should use the API console which takes care of all the formatting and authentication of requests for you. Until you need to test the calls themselves or use the return values, you can play around with the API console without needing to format things on the fly.

Making the request

Substituting our variables for your own, go ahead and make the cURL request. No data will be amended on Zencargo.

JSON Response

{
  "data": {
    "products": {
      "nodes": [
        {
          "skuCode": "SKUAX001"
        },
        {
          "skuCode": "SKUAX002"
        },
        # ...
      ]
    }
  }
}

Depending on whether you have data in your environment, you'll get back a response with some JSON similar to the one above - if you don't have data, then the nodes will be an empty array.

For now, congratulations, you just made your first call to the Zencargo API!

API rate limits

We limit the request rate to ensure fair access to our API across all our customers. If you exceed the rate limit, our server will respond with HTTP status code 429 (Too Many Requests). You should then consult the Retry-After response header, which states how many seconds you should wait before retrying your request.

Next Steps