Skip to content
Worlds API Docs

GraphQL Operations and Types

Operation Types

Queries

The Query type defines GraphQL operations that retrieve data from the server. It is the root type for all requests that require an immediate response and do not modify data stored within the Worlds system.

A quick note on pagination: Many queries are paginated to limit the number of results provided to a client to reasonable default volumes. Paging may be controlled by the client via the first and after arguments:

  • first is an Int argument that specifies how many results to return in the response. If not provided, a default value may be used.
  • after is a String argument that may be provided to contain a “cursor”, such as found on Edge types and the PageInfo type. This prompts the server to return only elements after the given cursor.

When using a cursor, identical arguments (including filters) should be provided to get expected results.

Mutations

The Mutation type GraphQL operations that change data on the server. Performing a mutation is analogous to performing HTTP verbs such as POST, PATCH, and DELETE.

Subscriptions

The Subscription type defines GraphQL operations that subscribe to ongoing events, for as long as the subscription connection persists.

Subscriptions to the Worlds server are handled using either the Server-Sent Events (SSE) protocol or the graphql-transport-ws protocol as defined by the graphql-ws library. For more information, see the server transports supported by Spring GraphQL. These protocols are supported by most of the popular GraphQL clients for receiving subscription information.

Data Types

Scalars

Scalars include primitive values, such as Boolean, Float, ID, Int or String.

When calling the GraphQL API, you must specify nested subfields until you return only scalars.

The Worlds API also defines several custom scalar types.

Enums

Enums represent possible sets of values for a field.

For example, the SortDirection is an enum because it may be ASC or DESC to represent sorting a specific field either in ascending or descending order.

Unions

A union is a type of object representing many objects.

For example, a field with the type GeoJSONGeometry could be either a GeoJSONPoint, GeoJSONPolygon, or a GeoJSONMultiPolygon because they are all part of the union. Using a union instead of an object gives you flexibility.

Directives

A directive adds additional configuration to the GraphQl schema.

For example, a field annotated with @deprecated is deprecated. A field annotated with @experimental is experimental and could be changed or deleted in the future.