1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
11 This document explains how to communicate with the A1 Mediator.
12 Information for maintainers of this platform component is in the Developer Guide.
17 Send the following JSON to create policy type 20008, which supports instances with
18 a single integer value:
24 "description": "tsa parameters",
25 "policy_type_id": 20008,
27 "$schema": "http://json-schema.org/draft-07/schema#",
35 "additionalProperties": false
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::
45 $ curl -X PUT --header "Content-Type: application/json" --data-raw @create.json "http://localhost/a1-p/policytypes/20008"
48 Send the following JSON to create an instance of policy type 20008:
57 For example, you can use the curl command-line tool to send this request::
61 $ curl -X PUT --header "Content-Type: application/json" --data '{"threshold" : 5}' "http://localhost/a1-p/policytypes/20008/policies/tsapolicy145"
64 Integrating Xapps with A1
65 -------------------------
67 The schema for messages sent by A1 to Xapps is labeled ``downstream_message_schema``
68 in the Southbound API Specification section below. A1 sends policy instance requests
69 using message type 20010.
71 The schemas for messages sent by Xapps to A1 appear in the Southbound API
72 Specification section below. Xapps must use a message type and content appropriate
75 #. When an Xapp receives a CREATE message for a policy instance, the Xapp
76 must respond by sending a message of type 20011 to A1. The content is
77 defined by schema ``downstream_notification_schema``. The most convenient
78 way is to use RMR's return-to-sender (RTS) feature after setting the
79 message type appropriately.
80 #. Since policy instances can "deprecate" other instances, there are
81 times when Xapps need to asynchronously tell A1 that a policy is no
82 longer active. Use the same message type and schema as above.
83 #. Xapps can request A1 to re-send all instances of policy type T using a
84 query, message type 20012. The schema for that message is defined by
85 ``policy_query_schema`` (just a body with ``{policy_type_id: ... }``).
86 When A1 receives this, A1 will send the Xapp a CREATE message N times,
87 where N is the number of policy instances for type T. The Xapp should reply
88 normally to each of those as the first item above. That is, after the Xapp
89 performs the query, the N CREATE messages sent and the N replies
90 are "as normal". The query just kicks off this process rather than
91 an external caller to A1.
94 Northbound API Specification
95 ----------------------------
97 This section shows the Open API specification for the A1 Mediator's
98 northbound interface, which accepts policy type and policy instance requests.
99 Following are the api and the response::
105 $ curl -v -X GET "http://localhost/a1-p/healthcheck"
111 #. Get all policy types
115 $ curl -X GET "http://localhost/a1-p/policytypes/"
119 [20001,5003,21001,21000,21002]
122 #. Get Policy Type based on policyid
126 $ curl -s -X GET "http://localhost/a1-p/policytypes/20001" | jq .
132 "$schema": "http://json-schema.org/draft-07/schema#",
134 "additionalProperties": false,
137 "description": "% Connections to block",
148 "description": "Sliding window length (in minutes)",
156 "description": "various parameters to control admission of dual connection",
157 "name": "admission_control_policy_mine",
158 "policy_type_id": 20001
162 #. Get all policy instances for a given policy type
166 $ curl -s -X GET "http://localhost/a1-p/policytypes/20001/policies/" | jq .
175 #. Get policy instance for a policy id and policy instance id
179 $ curl -s -X GET "http://localhost/a1-p/policytypes/20001/policies/1234" | jq .
186 "trigger_threshold": 20,
190 #. Create Policy type
194 $ curl -X PUT "http://localhost/a1-p/policytypes/21003/" -H "Content-Type: application/json" -d @policy_schema_ratecontrol.json
197 $ cat policy_schema_ratecontrol.json
202 "name": "Policy for Rate Control",
203 "policy_type_id":21003,
204 "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",
207 "$schema":"http://json-schema.org/draft-07/schema#",
209 "additionalProperties":false,
210 "required":["class"],
216 "description":"integer id representing class to which we are applying policy"
220 "description": "Whether to enable or disable enforcement of policy on this class"
226 "description":"Sliding window length in seconds"
228 "trigger_threshold":{
241 "downstream_schema":{
243 "additionalProperties":false,
244 "required":["policy_type_id", "policy_instance_id", "operation"],
250 "policy_instance_id":{
255 "enum":["CREATE", "UPDATE", "DELETE"]
258 "$schema":"http://json-schema.org/draft-07/schema#",
260 "additionalProperties":false,
261 "required":["class"],
267 "description":"integer id representing class to which we are applying policy"
271 "description": "Whether to enable or disable enforcement of policy on this class"
277 "description":"Sliding window length in seconds"
279 "trigger_threshold":{
296 "additionalProperties":false,
297 "required":["policy_type_id", "policy_instance_id", "handler_id", "status"],
303 "policy_instance_id":{
311 "enum":["OK", "ERROR", "DELETED"]
320 #. Create policy instance
324 $ curl -X PUT "http://localhost/a1-p/policytypes/21003/policies/1234" -H "Content-Type: application/json" -d @policy_instance_ratecontrol.json
326 $ cat policy_instance_ratecontrol.json
335 "trigger_threshold":10
339 #. Get policy instance status:
343 $ curl -s -X GET "http://localhost/a1-p/policytypes/21004/policies/1235/status" | jq .
348 "created_at": "0001-01-01T00:00:00.000Z",
349 "instance_status": "IN EFFECT"
353 #. Delete policy type
357 $ curl -s -X DELETE "http://localhost/a1-p/policytypes/21004/"
359 #. Delete policy instance
363 $ curl -s -X DELETE "http://localhost/a1-p/policytypes/21004/policies/1234/"
365 #. A1-EI data delivery for a job id:
369 $ curl -X POST "http://localhost/data-delivery" -H "Content-Type: application/json" -d @a1eidata.json
382 Southbound API Specification
383 ----------------------------
385 This section shows Open API schemas for the A1 Mediator's southbound interface,
386 which communicates with Xapps via RMR. A1 sends policy instance requests using
387 message type 20010. Xapps may send requests to A1 using message types 20011 and
391 .. literalinclude:: a1_xapp_contract_openapi.yaml