near-rt-ric-simulator/test/EXT_SRV/README.md

   1 # O-RAN-SC External Server extension for A1 Simulator
   2
   3 The O-RAN SC external server is an extension for A1 simulator. It creates an external web server building RESTful API. It is capable of recieving Rest calls from the northbound simulator version and responses back to it.
   4
   5 The external server supports GET, PUT and DELETE operations (version of the open API yaml file\):
   6
   7 | Yaml file version     | Version id          |
   8 | --------------------- | ------------------- |
   9 | EXT_SRV_api.yaml      |      0.0.1          |
  10
  11 The overall folder structure is \(relative to the location of this README file\):
  12
  13 | Dir              | Description |
  14 | ---------------- | ----------- |
  15 |.                 |Dockerfile, tox.ini and README |
  16 |api               |The open api yaml |
  17 |src               |Python source code |
  18 |certificate       |A self-signed certificate and a key |
  19 |docs              |Auto generated API descriptions in HTML format |
  20
  21 The external server handles the requests that are defined in the open API yaml file. All these requests are implemented in the server.py file in the src folder. In addition, a number of administrative functions are also supported and implemented by the main.py in the source folder.
  22
  23 The section below outlines the supported open api rest-based operations as well as the adminstrative operations.
  24
  25 # Ports and certificates
  26
  27 The external server normally opens the port 9095 for http. If a certificate and a key are provided the external server will open port 9195 for https instead. The port 9195 is only opened if a valid certificate and key is found.
  28 The certificate and key shall be placed in the same directory and the directory shall be mounted to /usr/src/app/cert in the container.
  29
  30 | Port     | Protocol |
  31 | -------- | ----- |
  32 | 9095     | http  |
  33 | 9195     | https |
  34
  35 The directory certificate contains a self-signed cert. Use the script generate_cert_and_key.sh to generate a new certificate and key. The password of the certificate must be set 'test'.
  36 The same urls are availables on both the http port 9095 and the https port 9195. If using curl and https, the flag -k shall be given to make curl ignore checking the certificate.
  37
  38 # Supported operations in External Server 0.0.1
  39
  40
  41 For the complete yaml specification, see [openapi.yaml](../api/EXT_SRV_api.yaml)
  42
  43 URIs for server:
  44
  45 | Function              | Path and parameters |
  46 | --------------------- | ------------------- |
  47 |  GET, Get all A1 policy ids | localhost:9095/a1policies |
  48 |  GET, Query for an A1 policy | localhost:9095/a1policy/{a1policyId} |
  49 |  PUT, Create an A1 policy | localhost:9095/a1policy/{a1policyId} |
  50 |  DELETE, Delete an A1 policy | localhost:9095/a1policy/{a1policyId} |
  51
  52 URIs for admin operations:
  53
  54 | Function              | Path and parameters |
  55 | --------------------- | ------------------- |
  56 |  POST, Delete all A1 policy instances | localhost:9095/serveradmin/deleteinstances |
  57 |  POST, Force a specific response code for all A1 operation | localhost:9095/serveradmin/forceresponse?code=500 |
  58 |  POST, Reset force response code | localhost:9095/serveradmin/forceresponse |
  59 |  POST, Force delayed response of all A1 operations | localhost:9095/serveradmin/forcedelay?delay=5 |
  60 |  POST, Reset force delayed response | localhost:9095/serveradmin/forcedelay |
  61
  62
  63 ## License
  64
  65 Copyright (C) 2022 Nordix Foundation.
  66 Licensed under the Apache License, Version 2.0 (the "License")
  67 you may not use this file except in compliance with the License.
  68 You may obtain a copy of the License at
  69
  70       http://www.apache.org/licenses/LICENSE-2.0
  71
  72 Unless required by applicable law or agreed to in writing, software
  73 distributed under the License is distributed on an "AS IS" BASIS,
  74 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  75 See the License for the specific language governing permissions and
  76 limitations under the License.
  77
  78 For more information about license please see the [LICENSE](LICENSE.txt) file for details.