GraphQLAPI

Table of Contents

• GraphQL API
  • Implementation details
• Mutations
• Subscriptions
  • Examples
    • Query about all VMs available for user
      • Input
      • Output

GraphQL API

The API is self-documented, you can view it in GraphiQL via /api/graphiql/, or view API graph via /voyager.

Implementation details

You are advised to read the GraphQL intro.

• the field names are expressed in snake_case in python code but they become camelCase in GraphQL API. So a field named nameLabel is expressed as name_label in python code.
• the type names for GraphQL output types start with G if there is a corresponding XenAPI class. So an output type for VM is GVM.
• the type names for GraphQL input types end with Input. So an input for VM is VMInput.

The directory structure in the source code is as follows:

/backend/handlers/graphql:
root.py - the definitions of Query, Mutation and Subscription.
graphql_handler.py - the defintions of GraphQL handlers and GraphQL context used in this API
interfaces/ - graphql interfaces
graphene_with_flags/ - a modified Graphene schema with support for enums acting as graphene_with_flags
mutation_utils/ - helpers for executing mutations
mutations/ - mutations for each API class
resolvers/ - query resolvers for each API class
types/base - basic GraphQL types
types/input - GraphQL input types
types/ - GraphQL output types
utils/ - various GraphQL generators
utils/querybuilder/: a RethinkDB query builder that uses

Mutations

Subscriptions

Subscriptions are available via /subscriptions, authentication is done via following payload:

{
"authToken": "'user' cookie set by server"
}

Authentication example (via Apollo's WebSocketLink):

import { WebSocketLink } from 'apollo-link-ws';

function getCookie(name) {
  function escape(s) { return s.replace(/([.*+?\^${}()|\[\]\/\\])/g, '\\$1'); }
  const match = document.cookie.match(RegExp('(?:^|;\\s*)' + escape(name) + '=([^;]*)'));
  return match ? match[1] : null;
}


// Create a WebSocket link:
const wsLink = new WebSocketLink({
  uri: `ws://localhost:3000/api/subscriptions`,
  options: {
    reconnect: true,
    connectionParams: {
      authToken: getCookie('user'),
    }
  }
});

Examples

Query about all VMs available for user

Input

query{
  vms{
    interfaces
    {
      id
      ip
      MAC
      attached
      status
      network {
        uuid
        nameLabel
        VMs
        {
          uuid
          nameLabel
        }
      }
    }
    nameLabel
    uuid
    nameDescription
    PVDriversVersion {
      major
      minor
      micro
      build
    }
    osVersion {
      name
      uname
      distro
      major
      minor
    }
    disks {
      id
      attached
      bootable
      device
      mode
      type
      VDI{
        nameLabel
        virtualSize
        ... on ISO
        {
          location
        }
        SR {

          nameLabel
          contentType
        }
      }
    }
  }
}

Output

{
  "data": {
    "vms": [
      {
        "interfaces": [
          {
            "id": "0",
            "ip": null,
            "MAC": "26:12:fd:75:41:63",
            "attached": true,
            "status": "",
            "network": {
              "uuid": "920b8d47-9945-63d8-4b04-ad06c65d950a",
              "nameLabel": "Pool-wide network associated with eth0",
              "VMs": [
                {
                  "uuid": "158e2b50-440e-f0bb-6b98-a9b8aaab1e25",
                  "nameLabel": "Create from Utility NEW"
                },
                null,
                null
              ]
            }
          }
        ],
        "nameLabel": "Create from Utility NEW",
        "uuid": "158e2b50-440e-f0bb-6b98-a9b8aaab1e25",
        "nameDescription": "",
        "PVDriversVersion": {
          "major": null,
          "minor": null,
          "micro": -1,
          "build": null
        },
        "osVersion": {
          "name": null,
          "uname": null,
          "distro": null,
          "major": null,
          "minor": null
        },
        "disks": [
          {
            "id": "OpaqueRef:6ed320d1-754e-efb3-d94c-5fd6cdb8e5d7",
            "attached": true,
            "bootable": true,
            "device": "xvda",
            "mode": "RW",
            "type": "Disk",
            "VDI": {
              "nameLabel": "0",
              "virtualSize": 209715200,
              "SR": {
                "nameLabel": "Local storage",
                "contentType": "user"
              }
            }
          },
          {
            "id": "OpaqueRef:ed08384d-1d53-f1f2-d1c2-e3faef2cb6df",
            "attached": true,
            "bootable": true,
            "device": "xvdb",
            "mode": "RO",
            "type": "CD",
            "VDI": {
              "nameLabel": "guest-tools.iso",
              "virtualSize": 71077888,
              "location": "guest-tools-7.11.0-1.iso",
              "SR": {
                "nameLabel": "XenServer Tools",
                "contentType": "iso"
              }
            }
          }
        ]
      }
    ]
  }
}