ballerina/graphql

Package Overview

This package provides an implementation for connecting and interacting with GraphQL endpoints.

Listener

The graphql:Listener is used to listen to a given port. Ballerina GraphQL is using HTTP as the underlying network protocol. To create a graphql:Listener, an http:Listener or a port number can be used.

Note: If the graphql:Listener is created using a port number, an http:Listener with the same port number should not be present.

Create a graphql:Listener using an http:Listener

1import ballerina/http;
2import ballerina/graphql;
3
4http:Listener httpListener = check new(4000);
5listener graphql:Listener graphqlListener = new(httpListener);

Create a graphql:Listener using port number

1import ballerina/graphql;
2
3listener graphql:Listener graphqlListener = new(4000);

Service

The Ballerina GraphQL service represents the GraphQL schema. When a service is attached to a graphql:Listener, a GraphQL schema will be auto-generated. The resource functions inside the service represent the resolvers of the root type. Then, the GraphQL listener will handle all the incoming requests and dispatch them to the relevant resource function.

Hello World

1import ballerina/graphql;
2
3service graphql:Service /graphql on new graphql:Listener(4000) {
4 resource function get greeting(string name) returns string {
5 return "Hello, " + name;
6 }
7}

The above can be queried using the GraphQL document below:

1{
2 greeting(name: "John")
3}

The result will be the following JSON.

1{
2 "data": {
3 "greeting": "Hello, John"
4 }
5}

For more information, see the following.

Return types

The Ballerina GraphQL resources can return the following types:

Scalar types

The following Ballerina types are considered as Scalar types:

  • int
  • string
  • boolean
  • float
  • decimal
1resource function get greeting() returns string {
2 return "Hello, World";
3}

This can be queried using the following document:

1{
2 greeting
3}

Result:

1{
2 "data": {
3 "greeting": "Hello, World"
4 }
5}

Record types

When a resource is returning a record type, each field of the record can be queried separately.

1public type Person record {|
2 string name;
3 int age;
4|};
5
6resource function get profile() returns Person {
7 return { name: "Walter White", age: 51 };
8}

This can be queried using the following document:

1{
2 profile {
3 name
4 age
5 }
6}

Result:

1{
2 "data": {
3 "profile": {
4 "name": "Walter White",
5 "age": 51
6 }
7 }
8}

Each field can be queried separately as shown in the following document:

1{
2 profile {
3 name
4 }
5}

Result:

1{
2 "data": {
3 "profile": {
4 "name": "Walter White"
5 }
6 }
7}

Arrays

A GraphQL resource can return an array of the types mentioned above. When a resource is returning an array, the result will return a JSON array.

1public type Person record {|
2 string name;
3 int age;
4|};
5
6resource function get people() returns Person[] {
7 Person p1 = { name: "Walter White", age: 51 };
8 Person p2 = { name: "James Moriarty", age: 45 };
9 Person p3 = { name: "Tom Marvolo Riddle", age: 71 };
10 return [p1, p2, p3];
11}

This can be queried using the following document:

1{
2 people {
3 name
4 }
5}

Result:

1{
2 "data": {
3 "people": [
4 {
5 "name": "Walter White"
6 },
7 {
8 "name": "James Moriarty"
9 },
10 {
11 "name": "Tom Marvolo Riddle"
12 }
13 ]
14 }
15}

Each element in the array consists only of the required name field.

Optional Types

A Ballerina GraphQL resource can return an optional type. When the return value is (), the resulting field in the JSON will be null.

1public type Person record {|
2 string name;
3 int age;
4|};
5
6resource function get profile(int id) returns Person? {
7 if (id == 1) {
8 return { name: "Walter White", age: 51 };
9 }
10}

This can be queried using the following document:

1{
2 profile(id: 1) {
3 name
4 }
5}

Result:

1{
2 "data": {
3 "profile": {
4 "name": "Walter White"
5 }
6 }
7}

If the following document is used:

1{
2 profile(id: 4) {
3 name
4 }
5}

This will be the result:

1{
2 "data": {
3 "profile": null
4 }
5}

Errors (With union)

A Ballerina GraphQL resource can return an error with the union of the types mentioned above.

1public type Person record {|
2 string name;
3 int age;
4|};
5
6resource function get profile(int id) returns Person|error {
7 if (id == 1) {
8 return { name: "Walter White", age: 51 };
9 } else {
10 return error(string `Invalid ID provided: ${id}`);
11 }
12}

This can be queried using the following document:

1{
2 profile(id: 5) {
3 name
4 }
5}

Result:

1{
2 "errors": [
3 {
4 "message": "Invalid ID provided: 5",
5 "locations": [
6 {
7 "line": 2,
8 "column": 4
9 }
10 ]
11 }
12 ]
13}

Additional Configurations

Additional configurations to a Ballerina GraphQL service can be provided using a service annotation (graphql:ServiceConfiguration).

Defining maximum query depth

When a maximum query depth is provided, all the queries exceeding that limit will be rejected at the validation phase and will not be executed.

1import ballerina/graphql;
2
3@graphql:ServiceConfiguration {
4 maxQueryDepth: 2
5}
6service graphql:Service /graphql on new graphql:Listener(9090) {
7 resource function get book(int id) returns Book {
8 // Logic
9 }
10}

The above service only accepts queries of less than 2 levels. For an example, consider the following document:

1{
2 book {
3 author {
4 books {
5 author {
6 books
7 }
8 }
9 }
10 }
11}

The result for the above query is the following JSON:

1{
2 "errors": [
3 {
4 "message": "Query has depth of 5, which exceeds max depth of 2",
5 "locations": [
6 {
7 "line": 1,
8 "column": 1
9 }
10 ]
11 }
12 ]
13}

Modules

[2]

graphql

This package provides an implementation for connecting and interacting with GraphQL endpoints.

graphql.parser

This package provides an implementation for connecting and interacting with GraphQL endpoints.

Listeners

[1]

Listener

Represents a Graphql listener endpoint.

Object Types

[1]

Service

Represents a GraphQL service

Records

[14]

__EnumValue

Represents a GraphQL enum.

__Field

Represents a GraphQL field.

__InputValue

Represents an input value for a GraphQL field.

__Schema

Represents a GraphQL schema.

__Type

Represents a GraphQL type.

Data

Represents the data in an output object for a GraphQL query.

ErrorDetail

Represents the details of an error occurred during parsing, validating, or executing a GraphQL document.

GraphqlServiceConfiguration

Provides a set of configurations for the GraphQL service.

ListenerConfiguration

Provides a set of configurations for configure the underlying HTTP listener of the GraphQL listener.

ListenerHttp1Settings

Provides settings related to HTTP/1.x protocol, when using HTTP 1.x as the underlying protocol for the GraphQL service.

ListenerSecureSocket

Configures the SSL/TLS options to be used for the underlying HTTP service used in GraphQL service.

Location

Represents a location in a GraphQL document.

OutputObject

Represents a GraphQL output object.

RequestLimitConfigs

Provides inbound request URI, total header and entity body size threshold configurations.

Enums

[1]

__TypeKind

Represents the type kind of a GraphQL type.

Annotations

[1]

ServiceConfiguration

The annotation to configure a GraphQL service.

Types

[1]

Scalar

Represents the supported Scalar types in Ballerina GraphQL module

Errors

[1]

Error

Represents any error related to the Ballerina GraphQL module