Working with GraphQL

GraphQL Overview

The Operavix system uses GraphQL as its API technology. GraphQL is an open-source query language for APIs that provides a more efficient and flexible alternative to traditional REST. While typical REST APIs require loading data from multiple URLs, GraphQL APIs allow you to retrieve all required data in a single request.

You can create and execute GraphQL queries using the built-in browser-based IDE (integrated development environment) GraphiQL. To access it, go to the system page and enter system_address/graphiql in the address bar.

When you edit a query in the built-in IDE, the URL updates automatically. Spaces, comments, and invalid queries are preserved. You can share the URL with colleagues.

GraphQL queries are interactive. This means you can modify a query and immediately see the updated result.

The GraphQL API supports auto-generated documentation, which is always up to date. To view it, open the Docs tab (located in the upper right corner) on the built-in IDE page. This section lists all queries available in Operavix.

GraphQL queries in the system are divided into three types:

• Query
• Mutation
• Subscription

Select the required group and find the query you need.

Each query description includes a list of fields and their data types.

For additional information about working with GraphQL, see the official website.

Authentication Methods and Working with GraphiQL

The built-in GraphiQL IDE is enabled for easier query creation and execution. To use it:

1. Log in to Operavix.
2. Go to: system_address/graphiql.

To execute a query from an external system, you must prepare an API key for authentication in the Settings / API Keys section. Two authentication modes are available for external systems using API keys:

• A standard API key is a character sequence that the external system must provide for authentication
• An SSL certificate. The external system first provides an API key, followed by mutual system authentication based on SSL certificates

Assign privileges to the created API key. For more information about configuring API key privileges, see API Key Access Rights.

Query on Behalf of an API Key

To execute a GraphQL query on behalf of an API key, include the key in the URL. Example: https://operavix.com/graphql?api_key=key

GraphQL Query Examples

The following are example GraphQL queries that can be used in the system.

Retrieving a Workspace

Query:

{
    workspace {
        workspace (id: 273) {
            id
            name
        }
    }
}

Response:

{
    "data": {
        "workspace": {
            "workspace": {
            "id": 273,
            "name": "test"
            }
        }
    }
}

Creating an Employee

Query:

mutation {
    employee {
        create (
            login: "test"
            first_name: "John"
            second_name: "Doe"
            language: ENGLISH
            phone_numbers: "12345678901"
        ){
            id
            login
            first_name
            second_name
            language
            phone_numbers
        }
    }
}

Response:

{
    "data": {
        "employee": {
            "create": {
                "id": 244,
                "login": "test",
                "first_name": "John",
                "second_name": "Doe",
                "language": "ENGLISH",
                "phone_numbers": [
                    "12345678901"
                ]
            }
        }
    }
}

Retrieving Employees with a Specific Access Role

Query:

{
    access_role {
        access_role (id:171) {
            employees {
                items {
                    id
                    first_name
                    second_name
                }
            }
        }
    }
}

Response:

{
  "data": {
    "access_role": {
      "access_role": {
        "employees": {
          "items": [
            {
              "id": 82,
              "first_name": "Alex",
              "second_name": "Morgan"
            },
            {
              "id": 142,
              "first_name": "Jordan",
              "second_name": "Lee"
            },
            {
              "id": 143,
              "first_name": "Taylor",
              "second_name": "Brooks"
            },
            {
              "id": 141,
              "first_name": "Casey",
              "second_name": "Bennett"
            }
          ]
        }
      }
    }
  }
}