The annotation to configure a GraphQL service.


ServiceConfiguration

GraphqlServiceConfiguration

# 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` 
```ballerina
import ballerina/http;
import ballerina/graphql;

http:Listener httpListener = check new(4000);
listener graphql:Listener graphqlListener = new(httpListener);
``` 

### Create a `graphql:Listener` using port number
```ballerina
import ballerina/graphql;

listener 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

```ballerina
import ballerina/graphql;

service graphql:Service /graphql on new graphql:Listener(4000) {
    resource function get greeting(string name) returns string {
        return "Hello, " + name;
    }
}
```

The above can be queried using the GraphQL document below:

```
{
    greeting(name: "John")
}
```

The result will be the following JSON.

```json
{
    "data": {
        "greeting": "Hello, John"
    }
}
```

For more information, see the following.
* [Hello World Example](https://ballerina.io/learn/by-example/graphql-hello-world.html)
* [Returning Records from GraphQL services](https://ballerina.io/learn/by-example/graphql-resources-with-record-values.html)
* [Hierarchical Resource Paths Example](https://ballerina.io/learn/by-example/graphql-hierarchical-resource-paths.html)

### 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`
     
```ballerina
resource function get greeting() returns string {
    return "Hello, World";
}
```

This can be queried using the following document:
```
{
    greeting
}
```

Result: 
```json
{
    "data": {
        "greeting": "Hello, World"
    }
}
```

#### Record types

When a resource is returning a record type, each field of the record can be queried separately.
  
```ballerina
public type Person record {|
    string name;
    int age;
|};

resource function get profile() returns Person {
    return { name: "Walter White", age: 51 };
}
```

This can be queried using the following document:
```
{
    profile {
        name
        age
    }
}
```

Result:
```json
{
    "data": {
        "profile": {
            "name": "Walter White",
            "age": 51
        }
    }
}
```

Each field can be queried separately as shown in the following document:
```
{
    profile {
        name
    }
}
```

Result:
```json
{
    "data": {
        "profile": {
            "name": "Walter White"
        }
    }
}
```

#### 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.
  
```ballerina
public type Person record {|
    string name;
    int age;
|};

resource function get people() returns Person[] {
    Person p1 = { name: "Walter White", age: 51 };
    Person p2 = { name: "James Moriarty", age: 45 };
    Person p3 = { name: "Tom Marvolo Riddle", age: 71 };
    return [p1, p2, p3];
}
```

This can be queried using the following document:
```
{
    people {
        name
    }
}
```

Result:
```json
{
    "data": {
        "people": [
            {
                "name": "Walter White"
            },
            {
                "name": "James Moriarty"
            },
            {
                "name": "Tom Marvolo Riddle"
            }
        ]
    }
}
```

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`.
  
```ballerina
public type Person record {|
    string name;
    int age;
|};

resource function get profile(int id) returns Person? {
    if (id == 1) {
        return { name: "Walter White", age: 51 };
    }
}
```

This can be queried using the following document:
```
{
    profile(id: 1) {
        name
    }
}
```

Result:
```json
{
    "data": {
        "profile": {
            "name": "Walter White"
        }
    }
}
```  

If the following document is used:
```
{
    profile(id: 4) {
        name
    }
}
```

This will be the result:
```json
{
    "data": {
        "profile": null
    }
}
``` 

#### Errors (With union)
A Ballerina GraphQL resource can return an `error` with the union of the types mentioned above.

```ballerina
public type Person record {|
    string name;
    int age;
|};

resource function get profile(int id) returns Person|error {
    if (id == 1) {
        return { name: "Walter White", age: 51 };
    } else {
        return error(string `Invalid ID provided: ${id}`);
    }
}
```

This can be queried using the following document:
```
{
    profile(id: 5) {
        name
    }
}
```

Result:
```json
{
    "errors": [
        {
            "message": "Invalid ID provided: 5",
            "locations": [
                {
                    "line": 2,
                    "column": 4
                }
            ]
        }
    ]
}
```  

### 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.

```ballerina
import ballerina/graphql;

@graphql:ServiceConfiguration {
    maxQueryDepth: 2
}
service graphql:Service /graphql on new graphql:Listener(9090) {
    resource function get book(int id) returns Book {
        // Logic
    }
}
```

The above service only accepts queries of less than 2 levels. For an example, consider the following document:
```
{
    book {
        author {
            books {
                author {
                    books
                }
            }
        }
    }
}
```

The result for the above query is the following JSON:

```json
{
    "errors": [
        {
            "message": "Query has depth of 5, which exceeds max depth of 2",
            "locations": [
                {
                    "line": 1,
                    "column": 1
                }
            ]
        }
    ]
}
```


Represents the type kind of a GraphQL type.


SCALAR

OBJECT

ENUM

NON_NULL

LIST

UNION

__TypeKind

Represents any error related to the Ballerina GraphQL module


Error

Invoked during the initialization of a `graphql:Listener`. Either an `http:Listner` or a port number must be
provided to initialize the listener.



init

An `http:Listener` or a port number to listen for the GraphQL service


listenTo

Configurations for the GraphQL service listener


configuration

ListenerConfiguration

A `graphql:Error` if the listener initialization is failed, otherwise nil


Attaches the provided service to the Listener.



attach

Service

name

A `graphql:Error`, if an error occurred during the service attaching process or the schema
generation process, otherwise nil


Detaches the provided service from the Listener.



detach

A `graphql:Error`, if an error occurred during the service detaching process, otherwise nil


'start

A `graphql:Error`, if an error occurred during the service starting process, otherwise nil


Gracefully stops the graphql listener. Already accepted requests will be served before the connection closure.



gracefulStop

A `graphql:Error`, if an error occurred during the service stopping process, otherwise nil


Stops the service listener immediately. It is not implemented yet.



immediateStop

Listener

string

__EnumValue

'type

__Type

args

__InputValue

__Field

Represents an input value for a GraphQL field.



The string reperesentation of the default value of the input argument


defaultValue

Represents a GraphQL schema. This will be auto-generated when a service is attached to the GraphQL listener.



types

The root operation type of the GraphQL service


queryType

__Schema

The `graphql:__TypeKind` type of the type


kind

The fields of the given type, if the type qaulifies to have fields


fields

The possible set of values, if the type is an enum


enumValues

If the type is a `NON_NULL` or a `LIST`, the `__Type` of the wrapped type


ofType

The list of types that can be represented from this type. Only applies for the Union types, and
the the list can only contain object types


possibleTypes

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


Data

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


message

locations

path

ErrorDetail

Provides a set of configurations for the GraphQL service.



maxQueryDepth

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


host

http1Settings

secureSocket

httpVersion

timeout

server

requestLimits

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


keepAlive

maxPipelinedRequests

ListenerHttp1Settings

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


mutualSsl

protocol

certValidation

ciphers

shareSession

handshakeTimeout

sessionTimeout

ListenerSecureSocket

Represents a location in a GraphQL document.


line

column

Location

The corresponding data for a GraphQL request


data

The errors occurred while processing a GraphQL request


errors

OutputObject

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


maxUriLength

maxHeaderSize

maxEntityBodySize

RequestLimitConfigs

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


Represents the supported Scalar types in Ballerina GraphQL module


boolean

float

Scalar

AUTO|ALWAYS|NEVER