Developer Resources

Learn about developing custom solutions for the application environment, including retrieving data from the application programmatically and embedding third-party web applications directly into the application interface.

  5 minute read  

Popular Topics

Use the following links to access popular topics. For general help using the application, browse through the topics in the navigation pane or type a search term in the search box.

  • Connect API Explorer
  • User Interface Extension SDK

API Terminology

The Connect API Explorer uses the GraphQL data query language. This topic contains a brief introduction to key GraphQL terminology and concepts.

For more information about GraphQL concepts, see http://graphql.org/.

Schema

The schema defines all of the application information that is available through the API, including the queries, mutations, objects, fields, arguments, and other items.

Each element in the schema has a property called a type. An element’s type determines how the values in an operation and a response are formatted, whether a request is valid, and how the GraphQL server processes each element of the schema.

GraphQL includes the following types:

  • Scalar types. For more information, see Scalars.
  • Object types. For more information, see Objects and fields.
  • Operations, also called root types. For more information, see Operations.

Conceptually, a GraphQL schema is organized in a hierarchy, as follows:

Object type {
Field
}
}

Scalars

Scalars represent concrete data, such as the names of users. The following scalar types are available.


Scalar type
Description
Usage notes

String
Text characters, including letters, numbers, punctuation, and spaces.
Enclose a string in double quotation marks. For example, users(lastName: “Gonzalez”).

Int
Integer numbers.
Provide an integer without any quotation marks. For example, users(id: 1234).

Boolean
The values true or false.
Provide a Boolean value without any quotation marks. For example, users(deleted: false).

Date
A date and time value, in Coordinated Universal Time (UTC).
Provide a date in the format YYYY-MM-DDThh:mm:ss, using a 24-hour clock. Enclose a date in double quotation marks. For example, statistics(startDate: “2017-12-31”).

Enum
A predefined set of values, which are defined in the schema. Short for enumeration.
Refer to the reference documentation to determine the values that are permitted for each enum.

Objects and fields

Objects are things that you might want to request information about, such as User or Case. Each object consists of a list of fields. Fields are specific pieces of information that describe an object. For example, the User object may have fields for firstName and email. Each field has a type, as follows:

  • Fields that describe simple data, such as the firstName field, have a scalar type.
  • Fields that describe complex data or relationships have an object type. Instead of returning one scalar value, a field with an object type can return any of the fields that are associated with that object. For example, the Users object includes a cases field that has the Cases object type. This means that in a request about users, you can nest your query to return information about the cases that are associated with those users.

To determine a field’s type, refer to the reference documentation.

Operations

Operations are actions that you can perform using the API. An operation is also called a root type. In GraphQL, the following operations are defined:

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

If you are familiar with REST (representational state transfer) APIs, you know that a REST API typically contains multiple endpoints. An endpoint is an access point into the API. In a REST API, the information that you can request is fixed for each endpoint. Depending on the information that is available through each endpoint, you may need to make multiple API calls to multiple endpoints to retrieve all of the information that you want.

In contrast, a GraphQL API contains a single endpoint, and the structure of the schema determines how you structure an operation. Because of this, the information that you can ask for in a single operation is flexible. You can ask for the specific information that you want to return. The server then returns only the information that you ask for.

When you write an operation, you must nest fields within the operation until all fields return scalars. For more information about scalars, see Scalars.

A GraphQL operation returns data as a JSON object. The structure of a response mirrors the structure of an operation. Because of this, you can predict what a response will look like based on what the query looks like.

For information about how to write operations in GraphQL, see Introduction to making API calls.

Arguments

Arguments are parameters that you can pass as part of an operation.

  • In queries, arguments allow you to pre-filter the results. For example, you can include the case name as an argument to pre-filter the results based on case.
  • In mutations, use arguments to define the information that you want to modify. Arguments consist of key-value pairs. The arguments that are available are defined in the schema. When you nest fields and objects within an operation, you can include a set of arguments with each field or object that supports arguments.

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.

For more information about variables, see Substitute placeholders for static data: variables.