WIP: Revamp docs with adding admin API draft.

 * refs lablup/backend.ai-manager#28, lablup/backend.ai-manager#31

 * Now we have a common JSON object reference. (WIP)

docs/admin-api/intro.rst

@@ -0,0 +1,18 @@
+Introduction
+============
+
+Sorna Admin API is for developing in-house management consoles.
+It requires a privileged keypair to invoke the admin APIs.
+It shares :doc:`the same request/response conventions of the user API </user-api/intro>`.
+
+Rate-limiting
+-------------
+
+The admin API does not have rate-limits.
+The Sorna gateway serves all incoming requests as much as possible for authenticated requests.
+
+Versioning
+----------
+
+To match the pace with the user API, the version of the admin API is paired with the corresponding user API.
+As we introduce the admin API since the user API v2, its initial version begins with v2.

docs/admin-api/keypairs.rst

@@ -0,0 +1,213 @@
+KeyPair Management
+==================
+
+Listing KeyPairs
+----------------
+
+* URI: ``/v2/admin/keypairs/:user``
+* Method: ``REPORT``
+
+Returns the list of keypairs associated with the given user UUID.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:user``
+     - ``str``
+     - The associated user ID.
+   * - ``paging``
+     - ``object``
+     - :ref:`paging-query-object`
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - The list of keypair is being returned.
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Fields
+     - Type
+     - Values
+   * - ``paging``
+     - ``object``
+     - :ref:`paging-info-object`
+   * - ``items``
+     - ``list[object]``
+     - A list of :ref:`keypair-item-object`
+
+Creating KeyPair
+----------------
+
+* URI: ``/v2/admin/keypairs/:user/create``
+* Method: ``POST``
+
+Creates a new keypair associated with the given user UUID.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:user``
+     - ``str``
+     - The associated user ID.
+       The exact format would depend on your user management system.
+   * - ``isActive``
+     - ``bool``
+     - If specified, set the key's initial activation status after creation.
+       (optional, default: ``true``)
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - A new keypair is being returned.
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Fields
+     - Type
+     - Values
+   * - ``accessKey``
+     - ``str``
+     - The access key part.
+   * - ``secretKey``
+     - ``str``
+     - The secret key part.
+
+Get Properties of KeyPair
+-------------------------
+
+* URI: ``/v2/admin/keypairs/:user/:accessKey``
+* Method: ``GET``
+
+Retrieves the current values of the given list of properties.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:user``
+     - ``str``
+     - The associated user ID.
+   * - ``:accessKey``
+     - ``slug``
+     - The access key of the keypair.
+   * - ``keys``
+     - ``list[str]``
+     - The list of the property names available in :ref:`keypair-props-object`.
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - The information is successfully returned.
+   * - 404 Not Found
+     - There is no such keypair.
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Fields
+     - Type
+     - Values
+   * - ``values``
+     - ``list[*]``
+     - The values of the request properties, in the same order of the request.
+
+Change Properties of KeyPair
+----------------------------
+
+* URI: ``/v2/admin/keypairs/:user/:accessKey``
+* Method: ``PATCH``
+
+Updates the given list of properties to the given values.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:user``
+     - ``str``
+     - The associated user ID.
+   * - ``:accessKey``
+     - ``slug``
+     - The access key of the keypair.
+   * - ``props``
+     - ``object``
+     - A part of :ref:`keypair-props-object` containing only modified properties.
+
+Deleting KeyPair
+----------------
+
+* URI: ``/v2/admin/keypairs/:user/:accessKey``
+* Method: ``DELETE``
+
+Delete a keypair. This is not a reversible operation, and only intended for use in database clean-ups.
+In most cases when you need to delete a keypair, deactivate it instead using the property change API above.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:user``
+     - ``str``
+     - The associated user ID.
+   * - ``:accessKey``
+     - ``slug``
+     - The access key of the keypair.

docs/admin-api/sessions.rst

@@ -0,0 +1,55 @@
+Kernel Session Monitoring
+=========================
+
+Listing Kernel Sessions
+-----------------------
+
+* URI: ``/v2/admin/sessions/:access_key``
+* Method: ``REPORT``
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``:access_key``
+     - ``slug``
+     - The access key.
+   * - ``filter``
+     - ``object``
+     - :ref:`session-filter-object`
+   * - ``paging``
+     - ``object``
+     - :ref:`paging-query-object`
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - The list of kernel sessions is being returned.
+
+
+.. list-table::
+   :widths: 15 5 80
+   :header-rows: 1
+
+   * - Fields
+     - Type
+     - Values
+   * - ``paging``
+     - ``object``
+     - :ref:`paging-info-object`
+   * - ``items``
+     - ``object``
+     - A list of :ref:`session-item-object`

docs/admin-api/stats.rst

@@ -0,0 +1,36 @@
+Statistics
+==========
+
+Per-keypair Usage Counter
+-------------------------
+
+* URI: ``/v2/admin/usage/:access_key``
+* Method: ``GET``
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``:access_key``
+     - The access key of the keypair.
+   * - ``keys``
+     - The comman-separated key list of desired statistic values.
+
+       Available keys are:
+
+       * storage
+
+Response
+""""""""
+
+Per-keypair Billing Calculator
+------------------------------
+
+* URI: ``/v2/admin/bill/:access_key``
+* Method: ``GET``
+

docs/api/auth.rst → docs/common-api/auth.rst

@@ -64,7 +64,7 @@ Common Structure of API Responses
    * - ``Link``
      - Web link headers specified as in `RFC 5988 <https://tools.ietf.org/html/rfc5988>`_. Only optionally used when returning a collection of objects.
    * - ``X-RateLimit-*``
-     - The rate-limiting information (see :doc:`/api/ratelimit`).
+     - The rate-limiting information (see :doc:`/common-api/ratelimit`).
    * - Body
      - JSON-encoded results