GraphQL Support

Webix provides full support for GraphQL API query language. GraphQL allows you to get all necessary data in one request.

Initialization

According to the philosophy of GraphQL all requests are sent to one endpoint. So, to start with, you need to specify the URL of your server from which data should be taken:

webix.proxy.GraphQL.url = "https://graphql-demo.webix.io/query";

To implement data loading and saving with GraphQL backend, you need to initialize Webix GraphQL proxy object via the webix.proxy() function that receives two parameters:

the proxy name, here it is GraphQL;
the query string starting from either query (for loading data) or mutation (for saving updates) keyword, both being the entities of the GraphQL language.

The GraphQL proxy has two methods: load() and save(), which can be used to trigger requests and, optionally, provide particular parameters for them. Both methods return a promise object which is resolved with the response data.

Loading data

//initialize a proxy
var graphql = webix.proxy("GraphQL", `query($rowId: Int!){
    getPackage(id: $rowId){
        id, 
        url,
        name
    }
}`);
 
//trigger the request
graphql.load({ 
    rowId: id.row 
}).then(data => $$("f2").setValues(data));

As a result, a POST request is triggered with the following parameters:

query: query string query($rowId: Int!){...}
variables: parameter passed as an argument of the load method { rowId: id.row }

Saving data

var pack = { id:1, title:"Some" };
var graphql = webix.proxy("GraphQL", `
    mutation updatePackage($pack: PackageInput!){
        updatePackage(package: $pack){
            id
        }
}`);
 
graphql.save({ 
    pack 
}).then(() => {
    $$("t2").updateItem(pack.id, pack);
    webix.message("Done")
});

As a result, a POST request is triggered with the following parameters:

query: query string mutation updatePackage($pack: PackageInput!){...}
variables: parameter passed as an argument of the save method { id:1, value:"Some" }

Related sample: Using GraphQL

Handling errors on the client side

You can handle errors on the client side by using the ignoreErrors property. By default this option is enabled, and errors are ignored. To catch errors, you need to enable the property like this:

webix.proxy.GraphQL.ignoreErrors = false;

If a response contains errors, data loading will be interrupted. The way of handling errors depends on the way of data loading:

if data is loaded via a widget, you can handle errors via the onLoadError event
in case of separate data loading, you can catch errors via the fail()/catch() methods of the promise

Using GraphQL with Data Components

You can use GraphQL to implement data loading and saving within Webix data components.

loading data

To enable GraphQL support for loading data into any data component, you need to connect the GraphQL proxy to its loading requests. For these needs, you should specify the url property as a proxy-->query string:

{
    view:"datatable",
    url: `GraphQL->{
        getAllProducts{
            docslink, name
        }
    }`
}

As a result, during loading the component will trigger a POST request with the mentioned query as a parameter:

{
    query:"
        {getAllProducts{docslink, name}}
    "
}

saving data

To save all client-side data changes to server, Webix Dataprocessor is used. It is initialized by providing saving logic in the component save property.

Within the save object you can provide the logic for particular operations: add, delete and update. Thus, you will get a separate response on each data operation.

{
    view:"datatable",
    save:{
        update:function(id, op, product){
            return webix.proxy("GraphQL", `
                mutation updateProduct($id: Int!, $product: ProductInput!){
                    updateProduct(id: $id, product: $product){
                        status
                    }
                }
            `).save({ id, product });
        },
        // other operations
    }
}

When you change a component data, its DataProcessor automatically triggers a POST request that contains the query field with the specified query string and the variables field with the data to save:

{
    query:"
        mutation updateProduct($id: Int!, $product: ProductInput!){
            updateProduct(id: $id, product: $product){
                status
            }
        }
    ",
    variables:{id: 966, product: {id: 966, name: "New Product1"}
}

Server-Side Response

A server-side response comes in the JSON format. An example of a GraphQL response to a successful request is:

{"data":{"getAllProducts":[
    {"docslink":"","name":"New Product1"},
    {"docslink":"","name":"New Product2"}
]}}

GraphQL proxy will convert the request so that it has the structure suitable for data components. For example, the above response will be transformed as follows:

[
    {"docslink":"","name":"New Product1"},
    {"docslink":"","name":"New Product2"}
]

For save operations we recommend you to return an object with the id of the changed data item and the status of operation:

{"data":{"addProduct":{"id":25,"status":"OK"}}}

DataProcessor will transform the response into a compact form:

{"id":25,"status":"OK"}

Handling errors on the server side

A successful GraphQL query is supposed to return a JSON object that contains a key:value pair, where the key is the "data" field and value is a complex object with received data. If the request fails or something goes wrong, a second key:value pair appears in the response, where the key is the "errors" field and the value is an array with errors objects.

{
    "data":{"updatePackage":null},
    "errors":[{"message":"record not found","path":["updatePackage"]}]
}

Read more about error handling aspects in the GraphQL specification.

Using Several Endpoints

In case you need to send requests to more than one server, there is such a possibility. You can add the path to the server as the third parameter of the webix.proxy function:

webix.proxy("GraphQL", `
    mutation updatePackage($pack: PackageInput!){
        updatePackage(package: $pack){
            id
        }
    }
`, "http://servername").load() //.save()