ballerina/graphql.parser : 0.2.0-alpha8

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.

Classes

[8]

ArgumentNode
CharReader
DocumentNode
FieldNode
FragmentNode
Lexer
OperationNode
Parser

Object Types

[3]

Node
ParentNode
Visitor

Records

[5]

ArgumentName
ArgumentValue
ErrorDetail

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

Location

Stores a location for an error in a GraphQL operation.

Selection

Constants

[5]

ANONYMOUS_OPERATION
T_BOOLEAN
T_FLOAT
T_INT
T_STRING

Enums

[1]

RootOperationType

Represents the types of operations valid in Ballerina GraphQL.

Types

[2]

ArgumentType
Scalar

Errors

[1]

Error

Represents the errors occurred while parsing a GraphQL document