User Guide and APIs

This document explains how to communicate with the A1 Mediator. Information for maintainers of this platform component is in the Developer Guide.

Example Messages

Send the following JSON to create policy type 20008, which supports instances with a single integer value:

{
  "name": "tsapolicy",
  "description": "tsa parameters",
  "policy_type_id": 20008,
  "create_schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "threshold": {
        "type": "integer",
        "default": 0
      }
    },
    "additionalProperties": false
  }
}

For example, if you put the JSON above into a file called “create.json” you can use the curl command-line tool to send the request:

.. code::

$ curl -X PUT –header “Content-Type: application/json” –data-raw @create.json “http://localhost/a1-p/policytypes/20008”

Send the following JSON to create an instance of policy type 20008:

{
  "threshold" : 5
}

For example, you can use the curl command-line tool to send this request:

.. code::

$ curl -X PUT –header “Content-Type: application/json” –data ‘{“threshold” : 5}’ “http://localhost/a1-p/policytypes/20008/policies/tsapolicy145”

Integrating Xapps with A1

The schema for messages sent by A1 to Xapps is labeled downstream_message_schema in the Southbound API Specification section below. A1 sends policy instance requests using message type 20010.

The schemas for messages sent by Xapps to A1 appear in the Southbound API Specification section below. Xapps must use a message type and content appropriate for the scenario:

  1. When an Xapp receives a CREATE message for a policy instance, the Xapp must respond by sending a message of type 20011 to A1. The content is defined by schema downstream_notification_schema. The most convenient way is to use RMR’s return-to-sender (RTS) feature after setting the message type appropriately.

  2. Since policy instances can “deprecate” other instances, there are times when Xapps need to asynchronously tell A1 that a policy is no longer active. Use the same message type and schema as above.

  3. Xapps can request A1 to re-send all instances of policy type T using a query, message type 20012. The schema for that message is defined by policy_query_schema (just a body with {policy_type_id: ... }). When A1 receives this, A1 will send the Xapp a CREATE message N times, where N is the number of policy instances for type T. The Xapp should reply normally to each of those as the first item above. That is, after the Xapp performs the query, the N CREATE messages sent and the N replies are “as normal”. The query just kicks off this process rather than an external caller to A1.

Northbound API Specification

This section shows the Open API specification for the A1 Mediator’s northbound interface, which accepts policy type and policy instance requests. Following are the api and the response:

#. Healthcheck

$ curl -v -X GET "http://localhost/a1-p/healthcheck"

< HTTP/1.1 200 OK

  1. Get all policy types

$ curl -X GET "http://localhost/a1-p/policytypes/"

[20001,5003,21001,21000,21002]

  1. Get Policy Type based on policyid

$ curl -s -X GET "http://localhost/a1-p/policytypes/20001" | jq .

{
  "create_schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "additionalProperties": false,
      "blocking_rate": {
        "default": 10,
        "description": "% Connections to block",
        "maximum": 1001,
        "minimum": 1,
        "type": "number"
      },
      "enforce": {
        "default": "true",
        "type": "boolean"
      },
      "window_length": {
        "default": 1,
        "description": "Sliding window length (in minutes)",
        "maximum": 60,
        "minimum": 1,
        "type": "integer"
      }
    },
    "type": "object"
  },
  "description": "various parameters to control admission of dual connection",
  "name": "admission_control_policy_mine",
  "policy_type_id": 20001
}

  1. Get all policy instances for a given policy type

$ curl -s -X GET "http://localhost/a1-p/policytypes/20001/policies/" | jq .

[
  "1234",
  "1235"
]

  1. Get policy instance for a policy id and policy instance id

$ curl -s -X GET "http://localhost/a1-p/policytypes/20001/policies/1234" | jq .

{
  "blocking_rate": 20,
  "enforce": true,
  "trigger_threshold": 20,
  "window_length": 20
}

  1. Create Policy type

$ curl -X PUT "http://localhost/a1-p/policytypes/21003/" -H "Content-Type: application/json" -d @policy_schema_ratecontrol.json


$ cat policy_schema_ratecontrol.json

{
"name": "Policy for Rate Control",
  "policy_type_id":21003,
  "description":"This policy is associated with rate control. Entities which support this policy type must accept the following policy inputs (see the payload for more specifics) : class, which represents the class of traffic for which the policy is being enforced",

  "create_schema":{
      "$schema":"http://json-schema.org/draft-07/schema#",
      "type":"object",
      "additionalProperties":false,
      "required":["class"],
      "properties":{
          "class":{
              "type":"integer",
              "minimum":1,
              "maximum":256,
              "description":"integer id representing class to which we are applying policy"
          },
          "enforce":{
              "type":"boolean",
              "description": "Whether to enable or disable enforcement of policy on this class"
          },
          "window_length":{
              "type":"integer",
              "minimum":15,
              "maximum":300,
              "description":"Sliding window length in seconds"
          },
          "trigger_threshold":{
              "type":"integer",
              "minimum":1
          },
          "blocking_rate":{
              "type":"number",
              "minimum":0,
              "maximum":100
          }

      }
  },

  "downstream_schema":{
      "type":"object",
      "additionalProperties":false,
      "required":["policy_type_id", "policy_instance_id", "operation"],
      "properties":{
          "policy_type_id":{
              "type":"integer",
              "enum":[21000]
          },
          "policy_instance_id":{
              "type":"string"
          },
          "operation":{
              "type":"string",
              "enum":["CREATE", "UPDATE", "DELETE"]
          },
          "payload":{
              "$schema":"http://json-schema.org/draft-07/schema#",
              "type":"object",
              "additionalProperties":false,
              "required":["class"],
              "properties":{
                  "class":{
                      "type":"integer",
                      "minimum":1,
                      "maximum":256,
                      "description":"integer id representing class to which we are applying policy"
                  },
                  "enforce":{
                      "type":"boolean",
                      "description": "Whether to enable or disable enforcement of policy on this class"
                  },
                  "window_length":{
                      "type":"integer",
                      "minimum":15,
                      "maximum":300,
                      "description":"Sliding window length in seconds"
                  },
                  "trigger_threshold":{
                      "type":"integer",
                      "minimum":1
                  },
                  "blocking_rate":{
                      "type":"number",
                      "minimum":0,
                      "maximum":100
                  }


              }
          }
      }
  },
  "notify_schema":{
      "type":"object",
      "additionalProperties":false,
      "required":["policy_type_id", "policy_instance_id", "handler_id", "status"],
      "properties":{
          "policy_type_id":{
              "type":"integer",
              "enum":[21000]
          },
          "policy_instance_id":{
              "type":"string"
          },
          "handler_id":{
              "type":"string"
          },
          "status":{
              "type":"string",
              "enum":["OK", "ERROR", "DELETED"]
          }
      }
  }
}

  1. Create policy instance

$ curl -X PUT "http://localhost/a1-p/policytypes/21003/policies/1234" -H "Content-Type: application/json" -d @policy_instance_ratecontrol.json

$ cat policy_instance_ratecontrol.json

{
    "class":12,
    "enforce":true,
    "window_length":20,
    "blocking_rate":20,
    "trigger_threshold":10
}

  1. Get policy instance status:

$ curl -s -X GET "http://localhost/a1-p/policytypes/21004/policies/1235/status" | jq .

{
  "created_at": "0001-01-01T00:00:00.000Z",
  "instance_status": "IN EFFECT"
}

  1. Delete policy type

$ curl -s -X DELETE "http://localhost/a1-p/policytypes/21004/"

  1. Delete policy instance

$ curl -s -X DELETE "http://localhost/a1-p/policytypes/21004/policies/1234/"

  1. A1-EI data delivery for a job id:

$ curl -X POST "http://localhost/data-delivery" -H "Content-Type: application/json" -d @a1eidata.json

$ cat a1eidata.json

{
"job":"100",
"payload":"payload"
}

Southbound API Specification

This section shows Open API schemas for the A1 Mediator’s southbound interface, which communicates with Xapps via RMR. A1 sends policy instance requests using message type 20010. Xapps may send requests to A1 using message types 20011 and 20012.

 1openapi: 3.0.0
 2info:
 3  version: 1.0.0
 4  title: Contract between A1 and RIC Xapps
 5
 6components:
 7  schemas:
 8
 9    policy_type_id:
10      description: >
11        represents a policy type identifier. Currently this is restricted to an integer range.
12      type: integer
13      minimum: 1
14      maximum: 2147483647
15
16    policy_instance_id:
17      description: >
18        represents a policy instance identifier. UUIDs are advisable but can be any string
19      type: string
20      example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"
21
22    policy_query_schema:
23      type: object
24      required:
25        - policy_type_id
26      additionalProperties: false
27      properties:
28        policy_type_id:
29          "$ref": "#/components/schemas/policy_type_id"
30
31    downstream_message_schema:
32      type: object
33      required:
34        - operation
35        - policy_type_id
36        - policy_instance_id
37        - payload
38      additionalProperties: false
39      properties:
40        operation:
41          description: the operation being performed
42          type: string
43          enum:
44            - CREATE
45            - DELETE
46            - UPDATE
47        policy_type_id:
48          "$ref": "#/components/schemas/policy_type_id"
49        policy_instance_id:
50          "$ref": "#/components/schemas/policy_instance_id"
51        payload:
52          description: payload for this operation
53          type: object
54      example:
55        operation: CREATE
56        policy_type_id: 12345678
57        policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
58        payload:
59          enforce: true
60          window_length: 10
61          blocking_rate: 20
62          trigger_threshold: 10
63
64    downstream_notification_schema:
65      type: object
66      required:
67        - policy_type_id
68        - policy_instance_id
69        - handler_id
70        - status
71      additionalProperties: false
72      properties:
73        policy_type_id:
74          "$ref": "#/components/schemas/policy_type_id"
75        policy_instance_id:
76          "$ref": "#/components/schemas/policy_instance_id"
77        handler_id:
78          description: >
79            id of the policy handler
80          type: string
81        status:
82          description: >
83            the status of this policy instance in this handler
84          type: string
85          enum:
86            - OK
87            - ERROR
88            - DELETED
89      example:
90        policy_type_id: 12345678
91        policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
92        handler_id: 1234-5678
93        status: OK