Manager GraphQL API

Backend.AI GraphQL API is for developing in-house management consoles.

There are two modes of operation:

  1. Full admin access: you can query all information of all users. It requires a privileged keypair.

  2. Restricted owner access: you can query only your own information. The server processes your request in this mode if you use your own plain keypair.

Warning

The Admin API only accepts authenticated requests.

Tip

To test and debug with the Admin API easily, try the proxy mode of the official Python client. It provides an insecure (non-SSL, non-authenticated) local HTTP proxy where all the required authorization headers are attached from the client configuration. Using this you do not have to add any custom header configurations to your favorite API development tools such as GraphiQL.

Basics of GraphQL

The Admin API uses a single GraphQL endpoint for both queries and mutations.

https://api.backend.ai/admin/graphql

For more information about GraphQL concepts and syntax, please visit the following site(s):

HTTP Request Convention

A client must use the POST HTTP method. The server accepts a JSON-encoded body with an object containing two fields: query and variables, pretty much like other GraphQL server implementations.

Warning

Currently the API gateway does not support schema discovery which is often used by API development tools such as Insomnia and GraphiQL.

Field Naming Convention

We do NOT automatically camel-case our field names. All field names follow the underscore style, which is common in the Python world as our server-side framework uses Python.

Common Object Types

ResourceLimit represents a range (min, max) of specific resource slot (key). The max value may be the string constant “Infinity” if not specified.

type ResourceLimit {
  key: String
  min: String
  max: String
}

KVPair is used to represent a mapping data structure with arbitrary (runtime-determined) key-value pairs, in contrast to other data types in GraphQL which have a set of predefined static fields.

type KVPair {
  key: String
  value: String
}

Pagination Convention

GraphQL itself does not enforce how to pass pagination information when querying multiple objects of the same type.

We use a pagination convention as described below:

interface Item {
  id: UUID
  # other fields are defined by concrete types
}

interface PaginatedList(
  offset: Integer!,
  limit: Integer!,
  # some concrete types define ordering customization fields:
  #   order_key: String,
  #   order_asc: Boolean,
  # other optional filter condition may be added by concrete types
) {
  total_count: Integer
  items: [Item]
}

offset and limit are interpreted as SQL’s offset and limit clauses. For the first page, set the offset to zero and the limit to the page size. The items field may contain from zero up to limit items. Use total_count field to determine how many pages are there. Fields that support pagination is suffixed with _list in our schema.

Custom Scalar Types

  • UUID: A hexademically formatted (8-4-4-4-12 alphanumeric characters connected via single hyphens) UUID values represented as String

  • DateTime: An ISO-8601 formatted date-time value represented as String

  • BigInt: GraphQL’s integer is officially 32-bits only, so we define a “big integer” type which can represent from -9007199254740991 (-253+1) to 9007199254740991 (253-1) (or, ±(8 PiB - 1 byte). This range is regarded as a “safe” (i.e., can be compared without loosing precision) integer range in most Javascript implementations which represent numbers in the IEEE-754 double (64-bit) format.

  • JSONString: It contains a stringified JSON value, whereas the whole query result is already a JSON object. A client must parse the value again to get an object representation.

Authentication

The admin API shares the same authentication method of the user API.

Versioning

As we use GraphQL, there is no explicit versioning. Check out the descriptions for each API for its own version history.