GraphQL terminology

Important

This part of the GraphQL API is currently in Early Availability status. For more information, see GraphQL API policy.

GraphQL is a completely different API framework than REST, and uses different terms to describe data and data structures. This section provides a brief introduction. For more details, refer to the GraphQL documentation.

Schemas

Unlike REST, GraphQL has a strong type system that services use to define an API's schema, the description of all objects available through an API and the operations that can be performed on those objects. You can explore the schema through introspection to see what is available, and build queries and mutations to retrieve or send the information that you need.

note

Schema introspection is not currently supported in the Preview release of the AppDirect GraphQL API. See Limitations for more information on limitations of the Preview release.

Queries and mutations

Queries represent requests for information, while mutations send information to the GraphQL server. In GraphQL, all requests, either query or mutation, are sent with a POST request. You indicate whether you are sending a query or mutation in the request body itself.

For more information, see Queries and Mutations.

Fields

A field is the smallest unit of data that you can retrieve, for example a name or ID. With GraphQL, you can query as many fields as required, and only the fields that you require, in a single request, even if those fields are contained within different objects.

For more information about fields, refer to the GraphQL documentation.

Arguments

Arguments are field values that you pass through mutations. You can pass arguments to multiple objects in a single request.

For more information about arguments, refer to the GraphQL documentation.

Connections and nodes

In GraphQL, connections represent collections of related data and nodes are items within that collection. For example, in the context of the AppDirect platform a list of products could be a connection and a specific product in that list would be a node.

Connections and nodes are concepts that fall within GraphQL's larger pagination model.

Pagination

When a query (or mutation) has the potential to return more than a single result in the response, you may want to organize how those results are returned in order to process them effectively.

GraphQL uses cursor-based pagination to organize results.

When a query may return multiple results, the API includes arguments you can use to specify the pagination. These may include either first / after for forward pagination, or last / before for backward pagination:

• first—A number of results to return after the specified after cursor. Must be a positive integer.

• after—The result to be used as a cursor. If null, the first number of results are returned starting at the beginning of the collection.

• last—A number of results to return before the specified before cursor. Must be a positive integer.

• before—The result to be used as a cursor. If null, the last number of results are returned starting at the end of the collection.

For more information on GraphQL pagination, see Pagination on the GraphQL Foundation site.