GraphQL

Access external GraphQL data sources from your functions

The Modus GraphQL API allows you to securely call and fetch data from any GraphQL endpoint.

Import

To begin, import the graphql namespace from the SDK:

GraphQL APIs

The APIs in the graphql namespace are below, organized by category.

We’re constantly introducing new APIs through ongoing development with early users. Open an issue if you have ideas on what would make Modus even more powerful for your next app!

Functions

execute

Execute a GraphQL statement to call a query or apply mutation against a GraphQL API endpoint.

graphql.execute<T> (
  hostName: string,
  statement: string,
  variables?: Variables
): Response<T>

T

Type

required

Type of object to use for the data returned from the query. This can be any type, including a custom type defined in your project. It should match the shape of the data returned from the GraphQL query.

Define custom types in the project’s source code. In AssemblyScript, create classes decorated with @json.

All types, including classes, base classes, and field types must be JSON serializable. You can also use built-in types such as strings, numbers, arrays, and maps.

hostName

string

required

Name of the host, as defined in the manifest.

statement

string

required

GraphQL statement containing the query or mutation operation to execute.

While it’s possible to directly include parameter values into your GraphQL statement, it’s highly recommended to pass a Variables object instead. This can help to prevent against injection attacks and other security vulnerabilities.

variables

Variables

Optional variables to include with the query.

See the details of the Variables object for more information.

Objects

Variables

class Variables {
  public set(name: string, value: any): void;
  public toJSON(): string;
}

A container for variables to include with a GraphQL operation.

To use this feature, create a new Variables object and call the set method for each variable you want to include. Then pass the object to the execute function.

set(name, value)

Set a variable with a name and value to include with the GraphQL operation.

name

string

required

The name of the variable to include in the GraphQL operation.

value

any

required

The value of the variable to include in the GraphQL operation.

The value can be of any type that’s JSON serializable, including strings, numbers, boolean values, arrays, maps, and custom objects decorated with @json.

toJSON()

string

Serializes the variables to a JSON string for inclusion in the GraphQL operation. The execute function calls this automatically when you pass a Variables object. You typically don’t need to call it directly.

Response

class Response<T> {
  errors: ErrorResult[] | null;
  data: T | null;
}

A response object from the GraphQL query.

Either errors or data is present, depending on the result of the query.

errors

ErrorResult[]

An array of errors incurred as part of your GraphQL request, if any.

Each error in the array is an ErrorResult object. If there are no errors, this field is null.

data

T

The resulting data selected by the GraphQL operation.

The data has the type specified in the call to the execute function. If data is absent due to errors, this field is null.

ErrorResult

class ErrorResult {
  message: string;
  locations: CodeLocation[] | null;
  path: string[] | null;
}

The details of an error incurred as part of a GraphQL operation.

message

string

Description of the error incurred.

path

string[]

Path to the area of the GraphQL statement related to the error.

Each item in the array represents a segment of the path.

locations

CodeLocation[]

An array of CodeLocation objects that point to the specific location of the error in the GraphQL statement.

CodeLocation

class CodeLocation {
  line: u32;
  column: u32;
}

The location of specific code within a GraphQL statement.

line

u32

Line number within the GraphQL statement for the code.

column

u32

Column number within the GraphQL statement for the code.