Understanding GraphQL: Queries, Mutations & Responses

Unlike REST APIs that use different HTTP verbs (GET, POST, DELETE) and endpoints for every resource, GraphQL uses a single endpoint. The action you perform is determined by the body of your request.

API Endpoint: https://graphql.tilaa.com/graphql/platform

1. Queries (Reading Data)

A Query is equivalent to a GET request. You use it to fetch data.
The power of GraphQL is that you specify exactly which fields you want back, preventing over-fetching of data.

Example: Fetching Namespace Registries

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

2. Mutations (Writing Data)

A Mutation is equivalent to POST, PUT, or DELETE. You use it to create, update, or destroy resources.

Example: Creating a Container

mutation CreateNewContainer(
  $image: String = "nginx:latest",
  $name: String = "my-web-server",
  $namespaceId: Int = 10,
  $specId: Int = 10
) {
  createContainer(
    containerInput: {
      namespaceId: $namespaceId,
      resourceSpecificationId: $specId,
      name: $name,
      image: $image
    }
  )
}

3. Understanding Responses

GraphQL responses are always returned in JSON format.

Success Response

If the operation succeeds, you receive a data object mirroring the structure of your query.

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

Error Response (HTTP 200)

If an error occurs (e.g., validation failure, not found), the API will still return an HTTP 200 OK status code. You must check the response body for the errors array.

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