GraphQL API

Tilaa offers the ability for you to execute CRUD method on resources (e.g. containers, container jobs etc.). The request needs to be sent to https://graphql.tilaa.com/graphql/platform, these requests need to contain an authorization token and one of the following: a query or a mutation.

Queries and Mutations

The differences between these two are as followed:

- Query: A GraphQL query is a request for data that is sent to the server. It specifies the fields that the client wants to retrieve from the server, and the server responds with the requested data in JSON format.

Example:

query MyQuery($name: String = "example") {
  namespace(name: $name) {
    privateRegistries {
      id
      name
    }
  }
}

- Mutation: A GraphQL mutation is a request to modify data on the server. it can create, update, or delete data, and it returns the modified data as a response.

Example:

mutation MyMutation($image: String = "example/test:latest", $name: String = "example", $namespaceId: Int = 10, $resourceSpecificationId: Int = 10) {
  createContainer(
    containerInput: {
      namespaceId: $namespaceId,
      resourceSpecificationId: $resourceSpecificationId,
      name: $name,
      image: $image
    }
  )
}

Responses

The response you will receive when executing a query will result in either success or failure. You do not receive status codes. When the query fails you will also get a message stating what went wrong for the query to fail, for example no resource with that specific name or the authorization token is wrong. And when the query succeeds you will naturally receive the data requested in the query.

Successful query example:

{
  "data": {
    "namespace": {
      "containerJobs": []
    }
  }
}

Failing query example:

{
  "errors": [
    {
      "message": "Not found."
    }
  ]
}

For a mutation a failing result will give similar responses. But when succeeding you will only receive a response with the action and true.

Success mutation example:

{
  "data": {
    "createContainer": true
  }
}

Failing mutation example:

{
  "errors": [
    {
      "message": "Variable \"$name\" of required type \"String!\" was not provided.",
      "locations": [
        {
          "line": 2,
          "column": 42
        }
      ]
    }
  ]
}

The fields that are required and also optional field can be found in the documentation at https://graphql.tilaa.com. You can also execute queries and mutations. To set them you can just select the attributes in the explorer. The queries and mutations are executed on the live server and not on a sandbox environment, so keep this in mind when execution queries and mutations.