Manager GraphQL API

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

두 가지 모드의 작업이 있습니다.

  1. 전체 관리자 접근 : 모든 사용자에 대한 모든 정보를 쿼리할 수 있습니다. 이 방법은 권한있는 키 쌍을 필요로 합니다.

  2. 제한된 사용자 계정 : 오직 본인의 정보에 대해서만 질문할 수 있습니다.만약 본인의 고유한 키 쌍을 사용한다면, 서버는 이 모드에서의 요청을 처리합니다.

경고

관리자 API는 오직 인증된 요청들만 받아들입니다.

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.

GraphQL의 기본

관리자 API는 단일 GraphQL 엔드포인트를 쿼리와 뮤테이션에 사용합니다.

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

GraphQL에 대한 개념과 구문에 대한 더 많은 정보를 위해서는, 다음 사이트를 방문하십시오.

HTTP 요청 규칙

클라이언트는 HTTP 메소드인 POST를 사용해야 합니다. 서버는 다른 GraphQL 서버 구현과 매우 유사한 쿼리``와 ``변수 두 가지 필드를 포함하는 JSON 인코딩 본문을 허용합니다.

경고

현재 API 게이트웨이는 Insomnia와 GraphiQL과 같은 API 개발 도구에서 자주 사용되는 스키마 검색을 지원하지 않습니다.

필드 명명 규칙

필드 네임을 자동으로 대문자로 만들지 않습니다. 서버 측의 프레임 워크가 파이썬을 사용하기 때문에 모든 필드 네임은 파이썬 상에서 일반적인 밑줄 스타일을 따릅니다.

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
}

페이지 번호 규칙

GraphQL 자체는 동일 유형의 다수 객체들에게 질문할 때, 페이지 번호 정보를전달하는 방법을 강요하지 않습니다.

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.

커스텀 스칼라 타입

  • 범용 고유 식별자 : ``문자열``로 표시되는 16진수 형식의 범용 고유 식별자 값(단일 하이픈으로 연결된 8-4-4-4-12 영숫자)

  • DateTime : ``문자열``로 표시되는 ISO-8601 형식의 날짜-시간 값

  • 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.

인증

관리자 API는 사용자 API와 같은 인증 방법을 공유한다.

버전관리

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