WIP: Refactor more JSON objects

docs/admin-api/keypairs.rst

@@ -105,8 +105,8 @@ Response
      - ``str``
      - The secret key part.
 
-Get Properties of KeyPair
--------------------------
+Getting KeyPair Properties
+--------------------------
 
 * URI: ``/v2/admin/keypairs/:user/:accessKey``
 * Method: ``GET``
@@ -158,8 +158,8 @@ Response
      - ``list[*]``
      - The values of the request properties, in the same order of the request.
 
-Change Properties of KeyPair
-----------------------------
+Updating KeyPair Properties
+---------------------------
 
 * URI: ``/v2/admin/keypairs/:user/:accessKey``
 * Method: ``PATCH``

docs/common-api/objects.rst

@@ -19,6 +19,7 @@ If ``index`` exceeds the number of pages calculated by the server, an empty list
    * - ``size``
      - ``int``
      - The number of items per page.
+       If set zero or this object is entirely omitted, all items are returned and ``index`` is ignored.
    * - ``index``
      - ``int``
      - The page number to show, zero-based.
@@ -95,7 +96,7 @@ KeyPair Properties Object
      - ``int``
      - Sets the number of instances clustered together when launching new machine learning kernel sessions. (default: ``1``)
    * - ``ML.instanceMemory``
-     - ``int`` (GiB)
+     - ``int`` (MiB)
      - Sets the memory limit of each instance in the cluster launched for new machine learning kernel sessions. (default: ``8``)
 
 The enterprise edition offers the following additional properties:
@@ -120,8 +121,8 @@ The enterprise edition offers the following additional properties:
 
 .. _session-filter-object:
 
-Session Filter Object
----------------------
+Kernel Session Filter Object
+----------------------------
 
 .. list-table::
    :widths: 15 5 80
@@ -137,8 +138,8 @@ Session Filter Object
 
 .. _session-item-object:
 
-Session Item Object
----------------------
+Kernel Session Item Object
+--------------------------
 
 .. list-table::
    :widths: 15 5 80
@@ -150,29 +151,38 @@ Session Item Object
    * - ``kernelId``
      - ``slug``
      - The kernel session ID.
+   * - ``type``
+     - ``str``
+     - The kernel type (typically the name of runtime or programming lanauge).
    * - ``status``
      - ``enum[str]``
      - One of ``"preparing"``, ``"building``", ``"running"``, ``"restarting"``, ``"resizing"``, ``"success"``, ``"error"``, ``"terminating"``, ``"suspended"``.
+   * - ``age``
+     - ``int`` (msec)
+     - The time elapsed since the kernel has started.
+   * - ``execTime``
+     - ``int`` (msec)
+     - The time taken for execution. Excludes the time taken for being suspended, restarting, and resizing.
    * - ``statusInfo``
      - ``str``
      - An optional message related to the current status. (e.g., error information)
-   * - ``usedMemory``
-     - ``int`` (KiB)
-     - The amount of memory currently using. It may show a stale value.
+   * - ``numQueriesExecuted``
+     - ``int``
+     - The total number of queries executed after start-up.
+   * - ``memoryUsed``
+     - ``int`` (MiB)
+     - The amount of memory currently used (sum of all resident-set size across instances). It may show a stale value.
    * - ``cpuUtil``
      - ``int`` (%)
      - The current CPU utilization (sum of all used cores across instances, hence may exceed 100%). It may show a stale value.
-   * - ``config.clusterSize``
-     - ``int``
-     - The configured number of instances bundled for this session.
-   * - ``config.instanceMemory``
-     - ``int`` (GiB)
-     - The configured memory size per instance.
+   * - ``config``
+     - ``object``
+     - :ref:`resource-config-object` specified when created.
 
-.. _resource-limit-object:
+.. _resource-config-object:
 
-Resource Limit Object
----------------------
+Resource Config Object
+----------------------
 
 .. list-table::
    :widths: 15 5 80
@@ -181,12 +191,12 @@ Resource Limit Object
    * - Key
      - Type
      - Description
-   * - ``maxMem``
-     - ``int`` (KiB)
-     - Maximum memory allowed.
-   * - ``execTimeout``
-     - ``int`` (msec)
-     - Maximum total CPU time.
+   * - ``clusterSize``
+     - ``int``
+     - The number of instances bundled for this session.
+   * - ``instanceMemory``
+     - ``int`` (MiB)
+     - The maximum memory allowed per instance.
 
 .. _vfolder-item-object:
 

docs/user-api/kernels.rst

@@ -1,8 +1,8 @@
 Kernel Management
 =================
 
-Creating a kernel session
--------------------------
+Creating Kernel Session
+-----------------------
 
 * URI: ``/v2/kernel/create``
 * Method: ``POST``
@@ -28,9 +28,9 @@ Parameters
      - ``str``
      - Client session token. Should be unique for continuous execution (for REPL).
 
-   * - ``limits``
+   * - ``config``
      - ``object``
-     - An optional :ref:`resource-limit-object` to specify resource requirements.
+     - An optional :ref:`resource-config-object` to specify resource requirements.
        Additional charges may apply on the public API service.
        If the requested limits exceeds our internal hard-limits,
        the API may return HTTP 406 "Not acceptable".
@@ -100,7 +100,7 @@ Example:
    }
 
 
-Getting kernel information
+Getting Kernel Information
 --------------------------
 
 * URI: ``/v2/kernel/:id``
@@ -145,57 +145,13 @@ Response
    * - Fields
      - Type
      - Values
-   * - ``lang``
-     - ``str``
-     - The kernel type.
-   * - ``age``
-     - ``int`` (msec)
-     - The time elapsed since the kernel has started.
-   * - ``idle``
-     - ``int`` (msec)
-     - The time elapsed since the kernel has generated any output.
-   * - ``queryTimeout``
-     - ``int`` (msec)
-     - The timeout for executing each query (the time between accepting a query and receiving the output) in milliseconds.
-       If exceeded, the kernel is automatically destroyed.
-   * - ``idleTimeout``
-     - ``int`` (msec)
-     - The maximum duration between queries.
-       If exceeded, the kernel is automatically destroyed.
-   * - ``maxCpuCredit``
-     - ``int`` (msec)
-     - The maximum amount of CPU time that this kernel can use.
-       If exceeded, the kernel is automatically destroyed.
-       If zero, there is no limit imposed.
-   * - ``numQueriesExecuted``
-     - ``int``
-     - The total number of queries executed after start-up.
-   * - ``memoryUsed``
-     - ``int`` (KiB)
-     - The amount of memory that this kernel is using now.
-   * - ``cpuCreditUsed``
-     - ``int`` (msec)
-     - The amount of CPU time that this kernel has used so far.
-
-Example:
-
-.. code-block:: json
-
-   {
-     "lang": "python3",
-     "age": 30220,
-     "idle": 1204,
-     "queryTimeout": 15000,
-     "idleTimeout": 3600000,
-     "maxCpuCredit": 0,
-     "numQueriesExecuted": 12,
-     "memoryUsed": 6531,
-     "cpuCreditUsed": 102
-   }
+   * - ``item``
+     - ``object``
+     - :ref:`session-item-object`.
 
 
-Destroying a kernel session
----------------------------
+Destroying Kernel Session
+-------------------------
 
 * URI: ``/v2/kernel/:id``
 * Method: ``DELETE``
@@ -231,8 +187,8 @@ Response
      - There is no such kernel.
 
 
-Restarting a kernel session
----------------------------
+Restarting Kernel Session
+-------------------------
 
 * URI: ``/v2/kernel/:id``
 * Method: ``PATCH``

docs/user-api/vfolders.rst

@@ -16,7 +16,7 @@ most kernels) as internally it uses a networked file system.
    limits are subject to change in the future.
 
 
-Listing virtual folders
+Listing Virtual Folders
 -----------------------
 
 Retruns the list of virtual folders created by the current keypair.
@@ -136,7 +136,7 @@ Example:
    }
 
 
-Getting virtual folder information
+Getting Virtual Folder Information
 ----------------------------------
 
 * URI: ``/v2/folders/:id``
@@ -186,8 +186,8 @@ Response
      - :ref:`vfolder-item-object`.
 
 
-Deleting a virtual folder
--------------------------
+Deleting Virtual Folder
+-----------------------
 
 * URI: ``/v2/folders/:id``
 * Method: ``DELETE``
@@ -230,7 +230,3 @@ Response
    * - 404 Not Found
      - There is no such folder.
 
-Acessing virtual folders via WebDAV
------------------------------------
-
-(TODO)