Introduction to Making API Calls

You can perform the following operations with the Connect API Explorer:

• Query: Requests data from the application.
• Mutation: Modifies data in the application.

A GraphQL operation returns data as a JSON object. The structure of a response mirrors the structure of an operation.

For information about JSON notation, see http://www.json.org/.

Request data: queries

To request data from the application, you perform a query.

About queries

A GraphQL query returns only the data that you specify in the query. To structure a query, you specify the objects and fields that you want to return. You must nest fields within a query until all fields return scalars. A scalar is concrete data, such as the name of a user.

Queries have the following structure:

query {
JSON objects to return
}

Optionally, you can include a unique name for each query, such as query yourQueryName { }.

Sample query

This example illustrates how to structure a query. You can work through the example yourself using the Connect API Explorer. For information about how to access the API explorer, see Access and use the Connect API Explorer.

The following query looks up the Clean_Enron case, and returns a list of users with their email addresses and portal user categories.

query {
cases(name: "Clean_Enron") {
name
users {
fullName
email
portalCategory
}
}
}

To understand how the query is structured, look at the query line-by-line:

• query {

To request data from the application, use the query operation.

• cases (name: "Clean_Enron") {

To start the query, request the cases object.

In the reference documentation, an exclamation mark (!) indicates that a field is required in an argument. Schema validation indicates that no arguments are required. Because an optional name argument is accepted, you can include the case name to pre-filter the results based on case name.

For information about how to access the reference documentation, see the reference documentation.

• users {

To return all of the users in the case, request the users object.

• The schema indicates that the users object has the Users object type. You can refer to the reference documentation for the Users object to determine which fields you want to request.

{
fullName
email
portalCategory
}

GraphQL and GraphQL Parser version upgrade

Connect API Explorer contains the latest upgraded version of GraphQL (v2.4.0) and GraphQL Parser (v4.1.2). These upgrades require a few minor changes to your existing API queries and codes that are declaring Date variables.

In any existing API queries, the Date variable needs to change from Date to DateTime. The following figure is an example of an existing query declaring a Date variable before the upgrade.

The following figure shows the needed change for the upgraded version of GraphQL.

Modify Data: mutations

To modify data in the application, you perform a mutation.

About mutations

To structure a mutation, you must specify the following information:

• Mutation name: The type of modification you want to perform.
• Input fields: The data that you want to send to the server. You pass the input fields as an argument to the mutation name. In the reference documentation, an exclamation mark (!) indicates that a field is required in an argument.
• Payload fields: The data that you want to return from the server. You pass the payload fields in the body of the mutation name.

Mutations have the following structure:

mutation {
mutationName(input argument key: {input fields for the mutation!}) {
payload fields for the mutation
}

If a mutation returns an object type as part of the payload, you can ask for nested fields of that object. This can be useful to determine information about an object after you update the object. For example, when you create a new annotation, you can return the new annotation’s ID as part of the mutation.

Sometimes, mutations require you to pass information that you cannot figure out without running a query. For example, to add an annotation to a document, you must provide the annotation type ID as an argument in the mutation. You can run a query first to determine the required information, and then perform a mutation using the data that was returned in the query.

Optionally, you can include a unique name for each mutation, such as mutation yourMutationName { }.

Sample mutation

This example illustrates how to structure a mutation.

The following mutation adds an annotation to a page in a document.

mutation {
annotationAdd(caseId: 6077, input: {
mainId: 22,
pageId: 68987,
pageNumber: 1,
annotationTypeId: "10068-31",
x1: 120,
x2: 499,
y1: 960,
y2: 1322,
color: BLACK,
referenceId: "abc"
}) {
totalCount
successCount
successItems {
referenceId
annotationId
}
errorCount
erroredItems {
referenceId
error
}
}
}

To understand how the mutation is structured, look at the mutation line-by-line:

• mutation {

  • To modify data in the application, use the mutation operation.

• annotationAdd(caseId: 6077, input: {mainId: 22, pageId: 68987, pageNumber: 1, annotationTypeId: "10068-31", x1: 120, x2: 499, y1: 960, y2: 1322, color: BLACK, referenceId: "abc"})

  • annotationAdd is the name of the mutation.

  • caseId is the input argument key that identifies the case. The argument value, 6077, indicates the ID of the case to make the annotation in.

  • input is the input argument key that identifies the annotation. The argument value, {mainId: 22, pageId: 68987, pageNumber: 1, annotationTypeId: "10068-31", x1: 120, x2: 499, y1: 960, y2: 1322, color: BLACK, referenceId: "abc"}, defines the annotation. In this mutation, the fields for the input argument key are an object, so you enclose them in curly braces.

  • In the reference documentation, an exclamation mark (!) indicates that a field is required in an argument. The caseId, mainId, pageId, and annotationTypeId fields are all required. For information about how to access the reference documentation, see reference documentation.

  • color is an enumeration type, also called an enum. An enum is a scalar that is restricted to a predefined set of values, which are defined in the schema. You can refer to the reference documentation to determine the values that are permitted for each enum.

  • annotationTypeId identifies the type of annotation. To determine the IDs of the annotation types that are available in a case, you can run a query before you perform the mutation:

    query {
    cases(id: 6077) {
    annotationTypes {
    id
    name
    }
    }
    }
    

• The schema indicates that the annotationAdd mutation has the AnnotationInsertResults object type. You can refer to the reference documentation for the AnnotationInsertResults object to determine which payload fields you want to request:

  {
  totalCount
  successCount
  successItems {
  referenceId
  annotationId
  }
  errorCount
  erroredItems {
  referenceId
  error
  }
  }
  

  • totalCount, successCount, and errorCount are optional fields.
  • successItems and erroredItems are optional objects. You can refer to the reference documentation to determine the fields that you can request for these objects.

Substitute placeholders for static data: variables

Variables allow you to represent the values in an argument with dynamic placeholders instead of static data values. This allows you to update the values that are passed in an operation without having to modify the operation itself.

About variables

To use a variable, do the following:

1. Define the variable outside of the operation. Do either of the following:

   • On the Connect API Explorer page, type the variable in the Query Variables pane. For more information about the Connect API Explorer, see Access and use the Connect API Explorer.
   • In a third-party application, create a variables object.

   Variables have the following structure:

   {
   "variableName": value
   }
   

   The variable must be valid JSON syntax.

2. Pass the variable as an argument to the operation:

   query($variableName: variableType) {
   JSON objects to return
   }
   

   You must define both the variable name and the variable type, such as String or Int. For more information about types, see API terminology.

3. Replace the static value in an argument with the variable:

   object(argumentKey: $variableName) {
   JSON fields to return
   }
   

Sample variables

This example illustrates how to structure a query that includes variables. You can work through the example yourself using the Connect API Explorer. For information about how to access the Connect API Explorer, see Access and use the Connect API Explorer.

The following variable definitions act as placeholders for a user’s first and last name.

{
"first_name_of_user": "John",
"last_name_of_user": "Smith"
}

The following query passes the variables, and then returns information about the user whose values you specified in the variable definition.

query ($first_name_of_user: String, $last_name_of_user: String) {
users(firstName: $first_name_of_user, lastName: $last_name_of_user) {
fullName
userName
email
lastLogin
}
}