graphql.md

GraphQL API

Sabakan provides GraphQL API at /graphql HTTP endpoint.

Schema

See gql/schema.graphql.

Playground

If sabakan starts with -enable-playground command-line flag, it serves a web-based playground for GraphQL API at /playground HTTP endpoint.

Examples

• Query
  • machine
  • searchMachines
• Mutation
  • setMachineState

Example: machine

Query:

query get($serial: ID!) {
  machine(serial: $serial) {
    spec {
      serial
      ipv4
    }
    status {
      state
    }
  }
}

Variables:

{
  "serial": "00000004"
}

Successful response

Get a machine with a given serial. It can be done with a GraphQL query and variables as follows:

Result:

{
  "data": {
    "machine": {
      "spec": {
        "serial": "00000004",
        "ipv4": [
          "10.0.0.104"
        ]
      },
      "status": {
        "state": "UNHEALTHY"
      }
    }
  }
}

Failure response

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

Example: searchMachines

Query:

query search($having: MachineParams = null, $notHaving: MachineParams = null) {
  searchMachines(having: $having, notHaving: $notHaving) {
    spec {
      serial
      labels {
        name
        value
      }
      ipv4
      rack
    }
    status {
      state
      timestamp
      duration
    }
  }
}

Variables:

{
    "having": {
        "labels": [
            {"name": "datacenter", "value": "dc1"}
        ],
        "states": ["HEALTHY"]
    },
    "notHaving": {
        "racks": [1]
    }
}

Successful response

Searching machines matching these conditions:

• the machine has a label whose key is "datacenter" and value is "dc1".
• the machine's current state is healthy.
• the machine is not in rack 1.

can be done with a GraphQL query and variables as follows:

Result:

{
  "data": {
    "searchMachines": [
      {
        "spec": {
          "serial": "00000004",
          "labels": [
            {
              "name": "datacenter",
              "value": "dc1"
            },
            {
              "name": "product",
              "value": "vm"
            }
          ],
          "ipv4": [
            "10.0.0.104"
          ],
          "rack": 0
        },
        "status": {
          "state": "HEALTHY",
          "timestamp": "2018-11-26T09:17:20Z",
          "duration": 21678.990289
        }
      }
    ]
  }
}

Failure responses

• No such machines found.

Result:

{
  "data": {
    "searchMachines": []
  }
}

Example: setMachineState

Query:

mutation {
  setMachineState(serial: "00000004", state: UNHEALTHY) {
    state
  }
}

Successful response

Set machine state unhealthy.

• the machine's current state is healthy.
• the machine's serial is 00000004.

can be done with a GraphQL query and variables as follows:

Result:

{
   "data": {
     "setMachineState": {
       "state": "UNHEALTHY"
     }
   }
 }

Failure responses

• Invalid state value.

{
  "errors": [
    {
      "message": "invalid state: RETIRE",
      "path": [
        "setMachineState"
      ],
      "extensions": {
        "type": "INVALID_STATE_NAME"
      }
    }
  ],
  "data": null
}

• Transitioning a retiring server to retired that still has disk encryption keys.

{
  "errors": [
    {
      "message": "encryption key exists",
      "path": [
        "setMachineState"
      ],
      "extensions": {
        "serial": "00000004",
        "type": "ENCRYPTION_KEY_EXISTS"
      }
    }
  ],
  "data": null
}

• No specified machine found.

{
  "errors": [
    {
      "message": "not found",
      "path": [
        "setMachineState"
      ],
      "extensions": {
        "serial": "00000007",
        "type": "MACHINE_NOT_FOUND"
      }
    }
  ],
  "data": null
}

• Invalid state transition.

Result:

{
  "errors": [
    {
      "message": "transition from [ healthy ] to [ uninitialized ] is forbidden",
      "path": [
        "setMachineState"
      ],
      "extensions": {
        "serial": "00000004",
        "type": "INVALID_STATE_TRANSITION"
      }
    }
  ],
  "data": null
}