docs/api.rst

   1 ..
   2       Copyright (c) 2019 AT&T Intellectual Property. All Rights Reserved.
   3
   4       Licensed under the Apache License, Version 2.0 (the "License");
   5       you may not use this file except in compliance with the License.
   6       You may obtain a copy of the License at
   7
   8           http://www.apache.org/licenses/LICENSE-2.0
   9
  10       Unless required by applicable law or agreed to in writing, software
  11       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  12       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  13       License for the specific language governing permissions and limitations
  14       under the License.
  15
  16 .. _api:
  17
  18 Radio Edge Cloud Remote Installer - Version 1
  19 =============================================
  20 The Akraino REC Remote Installer API is a RESTful interface used to trigger a
  21 deployment of a Radio Edge Cloud cluster from an Akraino Regional Controller.
  22
  23 For version 1 of the API, all endpoints are located under ``/v1/``.
  24
  25 The API runs on a CRUD model; Create (POST), Read (GET), Update (PUT), Delete (DELETE)
  26 operations may be performed although PUT and DELETE are not currently used.
  27 Not all operations may be allowed for all objects.
  28
  29 All content provided to the API must be in JSON form (with a Content-Type of
  30 ``application/json``).
  31 All output provided by the API will be in JSON form (with a Content-Type of
  32 ``application/json``).
  33
  34 At this time there is only the installation API.
  35
  36 .. _installation-api:
  37
  38 Installation API
  39 ----------------
  40 The Installation API allows a user to request or monitor an installation.
  41
  42 POST /v1/installations/
  43 ^^^^^^^^^^^^^^^^^^^^^^^
  44
  45 Provide a user config file which will be passed on to the REC deployer component
  46 and an ISO disk image containing the REC deployer. The user config file is often
  47 named user_config.yaml and an `example template`_ is available.
  48
  49 .. _example template: https://gerrit.akraino.org/r/gitweb?p=ta/config-manager.git;a=blob;f=userconfigtemplate/user_config.yaml;h=1e1e257efd99c433205d63d8fb75a821520a6d87;hb=refs/heads/master
  50
  51 Sample JSON input content:
  52
  53 .. code-block:: json
  54
  55   {
  56     "user-config": "<user config yaml filename>",
  57     "iso": "<iso-image-name>"
  58     "provisioning-iso": "<provisioning-iso-name>"
  59   }
  60
  61 Sample JSON response:
  62
  63 .. code-block:: json
  64   {
  65     "uuid": "<operation identifier>"
  66   }
  67
  68
  69 ===========  ======================================================================
  70 Return Code  Reason
  71 ===========  ======================================================================
  72 200          Successful initiation of installation.
  73 400          Invalid content supplied.
  74 500          Internal error.
  75 ===========  ======================================================================
  76
  77 GET /v1/installations/<uuid>/state
  78 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  79
  80 Retrieve the status of an installation (progress or completion).
  81
  82 Response body in JSON:
  83
  84 .. code-block:: json
  85
  86   {
  87    "status": <ongoing|completed|failed>,
  88    "description": <description about the progress>,
  89    "percentage": <percentage completed of the installation>
  90   }
  91
  92
  93 ===========  ======================================================================
  94 Return Code  Reason
  95 ===========  ======================================================================
  96 200          Successful execution.
  97 ===========  ======================================================================
  98
  99 POST /v1/installations/<uuid>
 100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 101
 102 Used by the REC deployer to report progress of an installation that was
 103 initiated by the Remote Installer
 104
 105 Request body in JSON:
 106
 107 .. code-block:: json
 108
 109   {
 110    "status": <ongoing|completed|failed>,
 111    "description": <description about the progress>,
 112    "percentage": <percentage completed of the installation>
 113   }
 114
 115 ===========  ======================================================================
 116 Return Code  Reason
 117 ===========  ======================================================================
 118 200          Successful execution.
 119 ===========  ======================================================================
 120