GraphQL for InterSystems platforms

GraphQL is a standard for declaring data structures and data retrieval methods, which acts as an additional layer between the client and the server. If this is your first time hearing about GraphQL, then here are a couple of good resources: one and two .

In this article I will tell you how you can use GraphQL in your projects on InterSystems technologies.

At the moment, on the platforms of InterSystems there are several ways to create client-server applications:

REST
Websocket
SOAP

But why is GraphQL so good? What new features will it give compared to, for example, REST?

There are several types of queries in GraphQL:

query is a request to the server to get data, just as in REST it is recommended to use GET requests to get data.
mutation - this type is responsible for changing data on the server. In REST to change data POST (PUT, DELETE) requests.
Mutations , like query, can return data - this is convenient if you want to request updated information from the server immediately after the mutation is completed.
subscriptions is the same type of query that will output data. The only difference is that the query runs from the rendering of the page on the client, and the subscriptions from the activation of mutations .

The main features of GraphQL and why it should be used.

The client decides that he wants to receive

One of the main features of GraphQL is that the structure and amount of data is determined by the client application. The client specifies exactly what data he wants to receive using a declarative, graph-like structure that is very similar to the JSON format. The response structure corresponds to the request structure.

This is a simple GraphQL query:

{ Sample_Company { Name } }

Answer in JSON format:

 { "data": { "Sample_Company": [ { "Name": "CompuSoft Associates" }, { "Name": "SynerTel Associates" }, { "Name": "RoboGlomerate Media Inc." }, { "Name": "QuantaTron Partners" } ] } }

Single entry point

In GraphQL for working with data, we always refer to a single entry point ( endpoint ) - GQL server. Changing the structure, fields, query parameters, we work with different data. The same REST has endpoint set.

Let's compare REST with GraphQL with a simple example:

Suppose you need to upload user content, for REST you need to make three requests to the server:

We load user data by its id
By id we get his posts
By id we get its subscribers

REST card corresponding to these requests:

  <Route Url="/user/:id" Method="GET" Call="GetUserByID"/> <Route Url="/user/:id/posts" Method="GET" Call="GetUserPostsByID"/> <Route Url="/user/:id/follovers" Method="GET" Call="GetUserFolloversByID"/>

To get a new set of data REST card will have to be supplemented with new endpoint.

GraphQL does the job in one query. To do this, you must specify the following in the request body:

 { operationName: null, // query    ( query TestName(...){...} ) query: "query { User(id: "ertg439frjw") { name posts { title } followers(last: 3) { name } } }", variables: null //  ,    query* }

REST card matching this request:

  <Route Url="/graphql" Method="POST" Call="GraphQL"/>

While this is the only endpoint on the server.

Install GraphQL and GraphiQL

In order to start using GraphQL you need to do a few steps:

Download the latest release from GitHub and import to the required area.
Go to the system management portal and create your new web application from the InterSystems Data Platform product (Caché, Ensemble or IRIS):
- Name - /
- Scope - for example SAMPLES
- Handler class - GraphQL.REST.Main
GraphiQL is a wrapper for testing GraphQL queries. Download the latest build release of GraphiQL or build it yourself.
Create a new web application:
- Name - / graphiql
- Scope - for example SAMPLES
- Physical path to CSP files - C: \ InterSystems \ GraphiQL \

Look at the result

Navigate to this browser http: // localhost: 57772 / graphiql / index.html (localhost - server, 57772 - port)

GraphiQL

I think with the Request and Answer area everything is clear, and the Scheme is the documentation that is generated for all the stored classes in the area.

The schema contains:

Classes
Properties, Arguments, and Their Types
Description of all of the above, which is generated from the comments

Consider the scheme on the example of the class Sample_Company :

Also, GraphiQL supports auto-completion, which can be called with the key combination Ctrl + Space :

Requests

Queries can be either simple or nested; you can query multiple data sets. Below is an example of a data request from two different classes Sample_Person and Sample_Company :

Filtration

Currently only strict equality is supported:

filter

Pagination

Implemented 4 functions for pagination, if necessary, they can be combined:

after: n - all entries with id greater than n
before: n - all entries with id less than n
first: n - the first n records
last: n - last n records

filters

Area of visibility

Most often, under the terms of the application business logic, for a particular client, not all classes of the region should be available, but those with which it has rights according to its role. Based on this, it is necessary to limit the visibility of classes for the client:

All classes in the field ( GraphQL.Scope.All )
Classes inherited from the superclass ( GraphQL.Scope.Superclass )
Classes belonging to a specific package ( GraphQL.Scope.Package )

To change the way visibility is limited, you need to open a studio, go to the desired area and open the GraphQL.Settings class. It has the SCOPECLASS parameter, its default value is GraphQL.Scope.All is a class that describes the interface for limiting the visibility of classes in a region:
scope
To change the visibility limit for classes, simply set one of the values above, GraphQL.Scope.Package or GraphQL.Scope.Superclass .

In the case of GraphQL.Scope.Package , you still need to go to this class and set the value of the Package parameter by the name of the required package, for example, Sample , then all the stored classes from this package will be available: