docs/user-guide-api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 User Guide and APIs
   5 ===================
   6
   7 .. contents::
   8    :depth: 3
   9    :local:
  10
  11 This document explains how to communicate with the A1 Mediator.
  12 Information for maintainers of this platform component is in the Developer Guide.
  13
  14 Example Messages
  15 ----------------
  16
  17 Send the following JSON to create policy type 20008, which supports instances with
  18 a single integer value:
  19
  20 .. code-block:: yaml
  21
  22     {
  23       "name": "tsapolicy",
  24       "description": "tsa parameters",
  25       "policy_type_id": 20008,
  26       "create_schema": {
  27         "$schema": "http://json-schema.org/draft-07/schema#",
  28         "type": "object",
  29         "properties": {
  30           "threshold": {
  31             "type": "integer",
  32             "default": 0
  33           }
  34         },
  35         "additionalProperties": false
  36       }
  37     }
  38
  39
  40 For example, if you put the JSON above into a file called "create.json" you can use
  41 the curl command-line tool to send the request::
  42
  43     curl -X PUT --header "Content-Type: application/json" --data-raw @create.json http://localhost/a1-p/policytypes/20008
  44
  45
  46 Send the following JSON to create an instance of policy type 20008:
  47
  48 .. code-block:: yaml
  49
  50     {
  51       "threshold" : 5
  52     }
  53
  54
  55 For example, you can use the curl command-line tool to send this request::
  56
  57     curl -X PUT --header "Content-Type: application/json" --data '{"threshold" : 5}' http://localhost/a1-p/policytypes/20008/policies/tsapolicy145
  58
  59
  60 Integrating Xapps with A1
  61 -------------------------
  62
  63 The schema for messages sent by A1 to Xapps is labeled ``downstream_message_schema``
  64 in the Southbound API Specification section below. A1 sends policy instance requests
  65 using message type 20010.
  66
  67 The schemas for messages sent by Xapps to A1 appear in the Southbound API
  68 Specification section below. Xapps must use a message type and content appropriate
  69 for the scenario:
  70
  71 #. When an Xapp receives a CREATE message for a policy instance, the Xapp
  72    must respond by sending a message of type 20011 to A1. The content is
  73    defined by schema ``downstream_notification_schema``.  The most convenient
  74    way is to use RMR's return-to-sender (RTS) feature after setting the
  75    message type appropriately.
  76 #. Since policy instances can "deprecate" other instances, there are
  77    times when Xapps need to asynchronously tell A1 that a policy is no
  78    longer active. Use the same message type and schema as above.
  79 #. Xapps can request A1 to re-send all instances of policy type T using a
  80    query, message type 20012.  The schema for that message is defined by
  81    ``policy_query_schema`` (just a body with ``{policy_type_id: ... }``).
  82    When A1 receives this, A1 will send the Xapp a CREATE message N times,
  83    where N is the number of policy instances for type T. The Xapp should reply
  84    normally to each of those as the first item above. That is, after the Xapp
  85    performs the query, the N CREATE messages sent and the N replies
  86    are "as normal".  The query just kicks off this process rather than
  87    an external caller to A1.
  88
  89
  90 Northbound API Specification
  91 ----------------------------
  92
  93 This section shows the Open API specification for the A1 Mediator's
  94 northbound interface, which accepts policy type and policy instance requests.
  95 Alternately, if you have checked out the code and are running the server,
  96 you can see a formatted version at this URL: ``http://localhost:10000/ui/``.
  97
  98
  99 .. literalinclude:: ../a1/openapi.yaml
 100    :language: yaml
 101    :linenos:
 102
 103
 104 Southbound API Specification
 105 ----------------------------
 106
 107 This section shows Open API schemas for the A1 Mediator's southbound interface,
 108 which communicates with Xapps via RMR. A1 sends policy instance requests using
 109 message type 20010. Xapps may send requests to A1 using message types 20011 and
 110 20012.
 111
 112
 113 .. literalinclude:: a1_xapp_contract_openapi.yaml
 114    :language: yaml
 115    :linenos: