GraphQL API Guide

Note

The GraphQL API is currently available at the following endpoint:

https://graph.cleverbridge.com/graphql

If you are interested in using this API, contact Client Experience.

The Cleverbridge GraphQL API is an alternative to the collection of REST APIs that we offer. By switching to the GraphQL API, you can take advantage of a number of its features, including the following:

  • Better query efficiency — You can now access numerous resources from a single endpoint.
  • No unnecessary data — It is now possible to get exactly what you need in a compact, concise payload.
  • More stability — GraphQL isn't tied to any specific database or storage engine. Instead, it is based on existing code and data.

At the moment, the GraphQL API can help you manage your customers, products and prices. As a result, you can use this API to renew customer license keys, resend customer emails, and update product descriptions, etc. After the integration, you can also use this tool to create customer self-service options and ensure that your internal product catalog is up-to-date.

To start using the API and learn more about its capabilities, see the following:

GraphQL vs. REST

The following examples illustrate some of the benefits of using our GraphQL API in comparison to the Cleverbridge Pricing API. As demonstrated in the REST examples, the user not only has to call a specific endpoint to obtain product and pricing information, but the content of the payload is standard, large, and tied to the /prices resource.

Example

On the other hand, when using GraphQL, the user can call one single endpoint and precisely define which data the API should return. This results in a smaller, more manageable payload.

Example

If necessary, the user can also call an additional resource in the same request (for example, biBookmark). In REST, the user would have to make two separate calls to two independent endpoints.

List of Queries and Mutations

The following are the queries and mutations currently available using the GraphQL API:

GraphQL Use Cases

The Cleverbridge GraphQL API is a powerful resource you can use in different ways. Following is a list of common scenarios and code examples to help you integrate and utilize the API.

Important Update

Important

If you already use GraphQL, be aware of the following changes related to the upcoming updates of some of its underlying components:

  1. DateTime input values will now follow the date and time notation according to ISO-8601 in order to avoid ambiguous dates such as "09-10-2015". A valid value would be "2022-05-21T10:00:00Z".

    Example of a new, correct input for a DateTime

    query ISO8601_example {
       exampleSearch(
          exampleSearchParameters: {
             dateTimeField: {
                value: "2022-05-21T10:00:00Z"
                secondValue: "2022-05-21T13:42:002Z"
                relationalOperator: BETWEEN }
       dateField: {
             value: "2022-05-21"
             secondValue: "2022-05-22"
             relationalOperator: BETWEEN }
       })
       {example { id } }
    } 					

  2. The value "null" will be treated as value "null" and not result in the default value for that field. Therefore, we advise that you do not include fields in your mutation calls if you want those fields to have their default value.

    Example of previously allowed input

    mutation MyMutation {
       createMvtCampaign(input: {
          clientId: 1584,
          name: "old Migration example",
          identifier: "old-Migration-example",
          isActive: null
    }) {
          createdMvtCampaign {
             isActive
          }
       }
    } 
    {
       "data": {
       "createMvtCampaign": {
          "createdMvtCampaign": {
             "isActive": true
             }
          }
       }
    } 

  3. Example of correct input now

    mutation MyMutation {
       createMvtCampaign(input: {
          clientId: 1584,
          name: "old Migration example",
          identifier: "old-Migration-example",
          isActive: null 
    }) {
          createdMvtCampaign {
             isActive
          }
       }
    } 
    {
       "data": {
       "createMvtCampaign": null
    },
    "errors": [
       {
             "message": "IsActive cannot be null."
          }
       ]
    } 

  4. The "code" property of errors will move into the "extensions" object inside of the error. To ensure a soft transition, we will not remove the old code property at first. However, we will remove it later, so we advise that you use the new field.
  5. Example of previously allowed input

    {
    "errors": [
       {
          "message": "Unauthenticated user.",
          "code": "Access forbidden" 
    		}
        ]
    } 

    Example of allowed input during the soft transition period

    { "errors": [ { "message": "Unauthenticated user.", "code": "Access forbidden", "extensions": { "code": "Access forbidden" } } ] }

    Final stage after a timespan to ensure a soft transition

    {
    "errors": [
       {
    	"message": "Unauthenticated user.",
    	"extensions": {   
    	   "code": "Access forbidden"
    		} 
         }
      ]
    } 

  6. Names of ENUM values must now follow the CAPITALIZED_WITH_UNDERSCORES format.

    Example

    In previous versions, multiple styles of naming conventions were allowed for enumerated values. For example, in RecommendationTypeEnum { CROSS_SELLING, SUB_SELLING, UP_SELLING } the value Up_SeLLINg was interpreted as UP_SELLING.

    Now, the CAPITALIZED_WITH_UNDERSCORES format has to be followed, so only the UP_SELLING name is correct. The Up_SeLLINg value would result in an error as converting to the correct syntax is no longer possible. Make sure you input your ENUM values using uppercase letters separated with underscores, if you want your ENUM-types to run smoothly.

  7. Providing a numeric value as string when using query variables is no longer possible. Now, this will result in a type error.
  8. Example of previously allowed input

    {
    	"query":"query example($id: Int!){ subscription(id: $id { id }}",
    	"variables":{"id":"49092971"}
    }

    Example of only allowed option now

    {
    	"query":"query example($id: Int!){ subscription(id: $id { id }}",
    	"variables":{"id":49092971}
    }