Forming calls with GraphQL

You can run queries on the Optimizely Data Platform (ODP) using GraphQL API and GraphQL Explorer.

Authenticating with GraphQL

The GraphQL Explorer uses the same authentication as ODP's REST APIs.

GraphQL Explorer

Optimizely Data Platform (ODP) GraphQL Explorer is an instance of GraphiQL, which is a "graphical interactive in-browser GraphQL IDE." There is a public version (safe for your customers to explore) and a private version (for your eyes only).

• Public Graph_i_QL: You can use this to explore both public and private schema based on the authentication method you choose. It requires you to paste your public/private API token into the API Key box.

• Private Graph_i_QL: You can use this to explore your full schema and gain experience writing GraphQL queries

GraphQL endpoint

The API has a single endpoint for each region (United States, Europe, and Asia-Pacific). More information about the different endpoints for the GraphQL API is available in the GraphQL API reference.

GraphQL queries

GraphQL queries return only the data you specify. To form a query, you must specify fields until you return only scalars. The following query looks up the customers dimension.

query {
customers {
   edges {
     node {
        first_name
        email
        name
     }
   }
 }
}

Handling errors

There are two general types of GraphQL operation errors:

• Parse or Validation errors
• Execution errors

Parse/Validation errors

Making a query with invalid query syntax or against fields that do not exist will fail client-side. Ensure that the GraphQL Schema is up-to-date on GraphQL Explorer.

Execution errors

Execution errors occur at the server while resolving the query operation. These errors may be the client's fault (like a bad request), others could be a server issue (like internal server errors).

Let us say the server could not find the customer with following query:

{
  customer(vuid: "notreal") {
    customer_id
    email
  }
}

The error response will look like the following. It includes the message field to explain the issue, theextensions.classification field represents where the error happens during the execution cycle and the extensions.code is a machine-readable error code.

{
    "errors": [
        {
            "message": "Exception while fetching data (/customer) : could not resolve vuid = notreal",
            "locations": [
                {
                    "line": 2,
                    "column": 5
                }
            ],
            "path": [
                "customer"
            ],
            "extensions": {
                "code": "INVALID_IDENTIFIER_EXCEPTION",
                "classification": "DataFetchingException"
            }
        }
    ],
    "data": {
        "customer": null
    }
}

Error codes