Update docs for the GraphQL-based Admin API

docs/admin-api/intro.rst

@@ -10,6 +10,16 @@ There are two modes of operation:
 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 <https://pypi.python.org/pypi/backend.ai-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.
+
 Basics of GraphQL
 -----------------
 
@@ -24,6 +34,27 @@ For more information about GraphQL concepts and syntax, please visit the followi
 * `GraphQL official website <http://graphql.org/>`_
 
 
+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.
+
+
 Pagination Convention
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -34,15 +65,21 @@ We use a de-facto standard pagination convention as described below:
 
 TODO
 
+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``
+
 
 Authentication
---------------
+~~~~~~~~~~~~~~
 
 The admin API shares the same authentication method of the user API.
 
 
 Versioning
-----------
+~~~~~~~~~~
 
 As we use GraphQL, there is no explicit versioning.
 You can use any version prefix in the endpoint URL, from ``v1`` to ``vN`` where

docs/admin-api/keypairs.rst

@@ -7,12 +7,63 @@ Full Admin
 Query Schema
 ~~~~~~~~~~~~
 
-TODO
+.. code-block:: text
+
+   type KeyPair {
+     access_key: String
+     secret_key: String
+     is_active: Boolean
+     is_admin: Boolean
+     resource_policy: String
+     created_at: DateTime
+     last_used: DateTime
+     concurrency_limit: Int
+     concurrency_used: Int
+     rate_limit: Int
+     num_queries: Int
+     vfolders: [VirtualFolder]
+     compute_sessions(status: String): [ComputeSession]
+   }
+
+   type root {
+     ...
+     keypairs(user_id: Int!, is_active: Boolean): [KeyPair]
+   }
 
 Mutation Schema
 ~~~~~~~~~~~~~~~
 
-TODO
+.. code-block:: text
+
+   input KeyPairInput {
+     is_active: Boolean
+     resource_policy: String
+     concurrency_limit: Int
+     rate_limit: Int
+   }
+
+   type CreateKeyPair {
+     ok: Boolean
+     msg: String
+     keypair: KeyPair
+   }
+
+   type ModifyKeyPair {
+     ok: Boolean
+     msg: String
+   }
+
+   type DeleteKeyPair {
+     ok: Boolean
+     msg: String
+   }
+
+   type root {
+     ...
+     create_keypair(user_id: Int!, props: KeyPairInput!): CreateKeyPair
+     modify_keypair(access_key: String!, props: KeyPairInput!): ModifyKeyPair
+     delete_keypair(access_key: String!): DeleteKeyPair
+   }
 
 
 Restricted Owner Access
@@ -21,7 +72,16 @@ Restricted Owner Access
 Query Schema
 ~~~~~~~~~~~~
 
-TODO
+It shares the same ``KeyPair`` type, but you cannot use ``user_id`` argument in the root query
+because the client can only query the keypair that is being used to make this API query.
+Also the returned value is always a single object.
+
+.. code-block:: text
+
+   type root {
+     ...
+     keypair(): KeyPair
+   }
 
 Mutation Schema
 ~~~~~~~~~~~~~~~

docs/admin-api/sessions.rst

@@ -7,7 +7,59 @@ Full Admin
 Query Schema
 ~~~~~~~~~~~~
 
-TODO
+.. code-block:: text
+
+   type ComputeSession {
+     sess_id: String
+     id: UUID
+     status: String
+     status_info: String
+     created_at: DateTime
+     terminated_at: DateTime
+     agent: String
+     container_id: String
+     mem_slot: Int
+     cpu_slot: Int
+     gpu_slot: Int
+     num_queries: Int
+     cpu_used: Int
+     max_mem_bytes: Int
+     cur_mem_bytes: Int
+     net_rx_bytes: Int
+     net_tx_bytes: Int
+     io_read_bytes: Int
+     io_write_bytes: Int
+     lang: String
+     workers(status: String): [ComputeWorker]
+   }
+
+   type ComputeWorker {
+     sess_id: String
+     id: UUID
+     status: String
+     status_info: String
+     created_at: DateTime
+     terminated_at: DateTime
+     agent: String
+     container_id: String
+     mem_slot: Int
+     cpu_slot: Int
+     gpu_slot: Int
+     num_queries: Int
+     cpu_used: Int
+     max_mem_bytes: Int
+     cur_mem_bytes: Int
+     net_rx_bytes: Int
+     net_tx_bytes: Int
+     io_read_bytes: Int
+     io_write_bytes: Int
+   }
+
+   type root {
+     ...
+     compute_sessions(access_key: String, status: String): [ComputeSession]
+     compute_workers(sess_id: String!, status: String): [ComputeWorker]
+   }
 
 
 Restricted Owner Access
@@ -16,4 +68,12 @@ Restricted Owner Access
 Query Schema
 ~~~~~~~~~~~~
 
-TODO
+It shares the same ``ComputeSession`` and ``ComputeWorker`` type, but with a slightly different root query type:
+
+.. code-block:: text
+
+   type root {
+     ...
+     compute_sessions(status: String): [ComputeSession]
+     compute_workers(sess_id: String!, status: String): [ComputeWorker]
+   }

docs/admin-api/vfolders.rst

@@ -0,0 +1,43 @@
+Virtual Folder Management
+=========================
+
+Full Admin
+----------
+
+Query Schema
+~~~~~~~~~~~~
+
+.. code-block:: text
+
+   type VirtualFolder {
+     id: UUID
+     host: String
+     name: String
+     max_files: Int
+     max_size: Int
+     created_at: DateTime
+     last_used: DateTime
+     num_files: Int
+     cur_size: Int
+   }
+
+   type rootQuery {
+     ...
+     vfolders(access_key: String): [VirtualFolder]
+   }
+
+
+Restricted Owner Access
+-----------------------
+
+Query Schema
+~~~~~~~~~~~~
+
+It shares the same ``VirtualFolder`` type, but you cannot use ``access_key`` argument in the root query.
+
+.. code-block:: text
+
+   type root {
+     ...
+     vfolders(): [VirtualFolder]
+   }

docs/common-api/objects.rst

@@ -143,28 +143,6 @@ Batch Execution Query Object
        under the working directory and copmiles them into ``./main``
        executable, with commonly used C/link flags: ``"-pthread -lm -lrt -ldl"``.
 
-   * - ``buildLog``
-     - ``bool``
-
-     - Indicates whether to separately report the logs from the build step.
-       (default: ``false``)
-
-       If set ``false``, all console outputs during the build step
-       are swallowed silently and only the console outputs from the main
-       program are returned.
-       This looks like you only run the main program with a hidden build step.
-
-       However, if the build command fails with a non-zero exit code, then the
-       ``"finished"`` response contains the swallowed console outputs of the
-       build command.  You can distinguish failures from the build step and the
-       execution step using ``result.options.step`` value.
-
-       If set ``true``, at least one ``"continued"`` response will be generated
-       to explicitly report the console outputs from the build step.
-       Like the execution step, there may be mulitple ``"continued"`` responses
-       with ``result.options.exitCode`` set ``null`` when the build step takes
-       long time.
-
    * - ``exec``
      - ``str``
 
@@ -174,6 +152,12 @@ Batch Execution Query Object
        performs the build step and ``options.buildLog`` is assumed to be
        ``true`` (the given value is ignored).
 
+.. note::
+
+   A client can distinguish whether the current output is from the build phase
+   or the execution phase by whether it has received ``build-finished`` status
+   or not.
+
 .. note::
 
    All shell commands are by default executed under ``/home/work``.
@@ -227,13 +211,17 @@ Execution Result Object
    * - ``status``
      - ``enum[str]``
 
-     - One of ``"continued"``, ``"waiting-input"``, ``"finished"``.
+     - One of ``"continued"``, ``"waiting-input"``, ``"finished"``, or ``"build-finished"``.
 
-       If this is ``"continued"``, you should repeat making another API call until you get ``"finished"`` status.
+       If this is ``"continued"``, the client should repeat making another API call until you get ``"finished"`` status.
        This happens when the user code runs longer than a few seconds, to allow the client to show its progress.
-       When each call returns, the below ``result.stdout`` and ``result.stderr`` fields have the console logs captured since the last previous call.
+       When each call returns, the below ``console`` field have the console logs captured since the last previous call.
        You should append returned console logs to your UI view to make it a complete log.
-       When making continuation calls, you should not put anything in ``code`` field of the request, otherwise you will get 400 Bad Request.
+       When making subsequent continuation calls, the client should send an "empty" execution request with the same value in the ``mode`` field.
+       Otherwise it will get 400 Bad Request.
+
+       (Batch mode only) If this is ``"build-finished"``, the client should repeat making another API call like ``"continued"``.
+       All outputs prior to this status return are from the build program and all future outputs are from the executed program built.
 
        If this is ``"waiting-input"``, you should make another API call with setting ``code`` field of the request to the user-input text.
        This happens when the user code calls interactive ``input()`` functions.
@@ -292,23 +280,6 @@ Execution Result Object
        different types of text boxes for user inputs.
 
 
-.. _session-filter-object:
-
-Kernel Session Filter Object
-----------------------------
-
-.. list-table::
-   :widths: 15 5 80
-   :header-rows: 1
-
-   * - Key
-     - Type
-     - Description
-   * - ``status``
-     - ``enum[str]``
-     - Either ``"ongoing"`` or ``"finished"``.
-       Note that ``"finished"`` status includes ``"success"`` and ``"error"`` only whereas ``"ongoing"`` includes all other status.
-
 .. _session-item-object:
 
 Kernel Session Item Object

docs/index.rst

@@ -82,6 +82,8 @@ Table of Contents
    admin-api/intro
    admin-api/keypairs
    admin-api/sessions
+   admin-api/vfolders
+   admin-api/stats
 
 .. _dev: