Operous GraphQL API reference

A summary of the capabilities of the Operous GraphQL API.

API Endpoints

Production:
https://app.operous.dev/graphql

Queries

server

Get a single server data according to the filter used

Returns an Server

Input

Name

Description

GetServerInput NON_NULL

Receives a hash with the attribute to filter the server result and its value

Example:

Query

{
  server(input:{value: "ubiquitous-chicken-8974", kind:NAME}){
    identifier
    name
  }
}

Response

{
  "data":  {
    "server": {
      "identifier": "7QiCIABxXyXe",
      "name": "webapp-01"
    }
  }
}

servers

Get all account servers registered can be filtered by a list of the server identifiers

Returns an Server NON_NULL,LIST,NON_NULL

Input

Name

Description

ListServerInput

Receives a list of IDs to filter the servers on the list

Example:

Query

{
  servers {
    identifier
    name
  }
}

Response

{
  "data": {
    "servers": [
      {
        "identifier": "gMAjMO8mkmhsFRxW",
        "name": "ancient-rock-700"
      },
      {
        "identifier": "7QiCIABxXyXe",
        "name": "webapp-01"
      }
    ]
  }
}

Mutations

registerServer

Starts the register of a new server on the Operous account

Input

Name

Description

RegisterServerInput NON_NULL

Receives the Operous unique registration token and the IP and port of the server to be registered

Example:

Query

mutation RegisterServer {
  registerServer(
    input: { token: "WBw98UVdPrN2", sshPort: 22, ssvIps: "185.76.253.221" }
  ) {
    ca
  }
}

Response

{
  "data": {
    "registerServer": {
      "ca": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEFUhjRNZfRqnbVUgPxi2bdhhPUQwL+K/bLrrpQXvSc6 Operous Test Runner"
    }
  }
}

confirmRegistration

Confirms the server registration at Operous

Returns an String

Input

Name

Description

ConfirmRegistrationInput NON_NULL

Receives the Operous unique registration token

Example:

Query

mutation ConfirmRegistration{
  confirmRegistration(input: { token: "WBw98UVdPrN2" })
}

Response

{
  "data": {
    "confirmRegistration": "stiff-authority-9065"
  }
}

checkToken

Check token legitimacy

Returns an String NON_NULL

This mutation does not need an input

Example:

Query

mutation{ checkToken }

Response

{
  "data":  {
    "checkToken": "Token is valid!"
  }
}

startTestRun

Starts an SSH test run on a determined server

Returns an Int NON_NULL

Input

Name

Description

StartTestRunInput NON_NULL

Receives an ID to select the correct server for the test execution

Example:

Query

mutation {
  startTestRun (input: {serverId: "7QiCIABxXyXe"})
}

Response

{
  "data":  {
    "startTestRun": 1
  }
}

Types

DateTime

A specific point in time

TestRunStatus

Status available for a test run

Enum Name Description

FAILED

The Test Run could not run or it finished with some failing tests

SUCCESS

The Test Run finished execution with success, and the server passed in all the tests

RUNNING

The Test Run is still in progress

ServerFilterKind

Determines which attribute from the server will be used to filter

Enum Name Description

ID

The server external ID

NAME

The server name

Errors

Errors the API can return

Enum Name Description

INVALID_SERVER_REGISTER_TOKEN

The token used to register the server is invalid. Maybe it expired, maybe it never existed.

UNAUTHENTICATED_REQUEST

The operation requires user authentication

MAXIMUM_ACCOUNT_QUOTA

The operation requested was not permitted because the account have reached the usage quota

ACCOUNT_QUOTA_CHECK

The operation could not proceed because there was a failure while checking the account usage

TestRun

A Test Run that is running or already was executed at a server

Field Name Description

number - Int NON_NULL

This number is scoped to the server. If the number is 4, this Test Run server represents the fourth test execution in the related server.

time - DateTime NON_NULL

The Test Run start time

status - TestRunStatus NON_NULL

The test current status

tests - Test NON_NULL,LIST,NON_NULL

The tests executed in this Test Run

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Server

A physical or virtual on-premise, private, or public cloud server that must be registered to be tested by Operous. A server must belong to an Operous account.

Field Name Description

identifier - ID NON_NULL

The server immutable identifier

name - String NON_NULL

A name for this server, can be edited

testRun - TestRun

Server specific Test Run information

testRuns - TestRun NON_NULL,LIST,NON_NULL

Server list of Test Runs

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Test

A test executed in a Test Run

Field Name Description

id - String

The test identifier

text - String

The test full message. It informs what was tested and what issue was found

passed - Boolean

If this test has passed

Boolean

The Boolean scalar type represents true or false.

RegisterServerResponse

The register will respond with the CA key to be configured on the server

Field Name Description

ca - String NON_NULL

Certificate authority key

GetServerInput

Receives a hash with the attribute to filter the server result and its value

Input Field Description

value - String NON_NULL

Attribute value used to filter

kind - ServerFilterKind NON_NULL

An enum to determine which attribute from the server will be used to filter

ListServerInput

Information used to filter the servers on the servers query

Input Field Description

identifier - ID LIST,NON_NULL

List of server identifiers

StartTestRunInput

Information used to start a Test Run at Operous

Input Field Description

serverId - ID NON_NULL

server identifier

RegisterServerInput

Information used to register a new server on the Operous account

Input Field Description

token - String NON_NULL

The token used to register the server

ssvIps - String NON_NULL

A list of IPs separated by spaces

sshPort - Int NON_NULL

The port used to perform an SSH connection at this server

ConfirmRegistrationInput

Information used to confirm the server registration at Operous

Input Field Description

token - String NON_NULL

The token used to register the server