docs/policy-agent-api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2020 Nordix
   4
   5 .. |nbsp| unicode:: 0xA0
   6    :trim:
   7
   8 .. |nbh| unicode:: 0x2011
   9    :trim:
  10
  11 .. _policy-agent-api:
  12
  13 ############################
  14 A1 Policy Management Service
  15 ############################
  16
  17
  18 *******************************************
  19 A1 Policy Management Service - Introduction
  20 *******************************************
  21
  22 The A1 Policy Management Service ("Policy Agent") is an SMO/NONRTRIC service above the NONRTRIC A1 Adaptor/Controller
  23 that provides:
  24
  25 * Unified REST & DMAAP APIs for managing A1 Policies in all Near |nbh| RT |nbsp| RICs
  26 * Synchronized view of registered "services" (e.g. R-APP, GUI, etc)
  27 * Synchronized view of policy instances for each "service"
  28 * Synchronized view of policy instances in all Near |nbh| RT |nbsp| RICs
  29 * Synchronized view of policy types in all Near |nbh| RT |nbsp| RICs
  30 * Policy Query API (e.g. per Near |nbh| RT |nbsp| RIC, per "service", per policy type)
  31 * An initial interface for unified Near |nbh| RT |nbsp| RIC ID to Near |nbh| RT |nbsp| RIC address mapping.
  32   (Note:  may also later act as adaptor to A&AI, CMDBs etc. to "find" Near |nbh| RT |nbsp| RICs - TBC)
  33 * An Initial "O1 ManagedElement" mapping database & interface to find appropriate Near |nbh| RT |nbsp| RIC for RAN elements.
  34   (Note: may also later act as adaptor to A&AI, RuntimeDB, other CMDBs etc. - TBC)
  35 * Monitors all Near |nbh| RT |nbsp| RICs and recovers from inconsistencies (Note: e.g. Near |nbh| RT |nbsp| RIC restarts)
  36 * Support for different Southbound connectors on a per Near |nbh| RT |nbsp| RIC basis. (Note: e.g. different A1
  37   versions, different Near |nbh| RT |nbsp| RIC versions, different A1 adapters, different or proprietary A1
  38   controllers/EMSs)
  39
  40 ***************************************
  41 A1 Policy Management Service - REST NBI
  42 ***************************************
  43
  44 This is the north bound API of the A1 Policy Management Service ("Policy Agent"). This API allows *services* to interact
  45 with the Policy Agent using REST.
  46
  47 By registering with the Policy Agent, the Policy Agent takes responsibility for synchronizing the policies created by
  48 the service in the Near |nbh| RT |nbsp| RICs. This means that if a Near |nbh| RT |nbsp| RIC restarts, the Policy Agent
  49 will try to recreate all the policies residing in the Near |nbh| RT |nbsp| RIC once it is started again. If this is not
  50 possible, it will remove all policies belonging to the Near |nbh| RT |nbsp| RIC.
  51
  52 The Policy Agent also keeps an updated view of the policy types available, and which Near |nbh| RT |nbsp| RICs that
  53 support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain
  54 Near |nbh| RT |nbsp| RIC.
  55
  56 The Policy Agent NBI has four distinct parts, described in the sections below:
  57
  58 * Service Management
  59 * Policy Management
  60 * Near-RT RIC Repository
  61 * Health Check
  62
  63 Service Management
  64 ==================
  65
  66 A service can register itself in the Policy Agent.
  67
  68 By providing a callback URL the service can get notifications from the Policy Agent.
  69
  70 A service can also register a "*Keep Alive Interval*", in seconds. By doing this the service promises to call the
  71 Policy Agent's "*Keep Alive*" method, or else create or delete policies, more often than the "*Keep Alive Interval*"
  72 measured in seconds. If the service, for some reason, is not able to do this, the Policy Agent will consider that the
  73 service has died or vanished and will then delete all its policies, both in the internal repository and in the
  74 Near |nbh| RT |nbsp| RICs where they were earlier created. **Note!** |nbsp| If the service does not provide a value for
  75 "*Keep Alive Interval*", then the service maintains full responsibility to delete all of its policies when they are no
  76 longer needed.
  77
  78 Service Management Operations
  79 -----------------------------
  80
  81 /service
  82 ~~~~~~~~
  83
  84 PUT
  85 +++
  86
  87 Register a service.
  88
  89 **URL path:**
  90   /service
  91
  92 **Parameters:**
  93   None.
  94
  95 **Body:**  (*Required*)
  96     A JSON object (ServiceRegistrationInfo): ::
  97
  98       {
  99         "callbackUrl": "string",         (An empty string means the service will never get any callbacks.)
 100         "keepAliveIntervalSeconds": 0,   (0 means the service will always be considered alive.)
 101         "serviceName": "string"          (Required, must be unique.)
 102       }
 103
 104 **Responses:**
 105   200:
 106         Service updated.
 107   201:
 108         Service created.
 109   400:
 110         The ServiceRegistrationInfo is not accepted.
 111
 112 **Examples:**
 113   **Call**: ::
 114
 115     curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d '{
 116         "callbackUrl": "URL",
 117         "keepAliveIntervalSeconds": 0,
 118         "serviceName": "existing"
 119       }'
 120
 121   Result:
 122     201: ::
 123
 124        OK
 125
 126   **Call**: ::
 127
 128      curl -X PUT "http://localhost:8081/service" -H  "Content-Type: application/json" -d "{}"
 129
 130   Result:
 131      400: ::
 132
 133        Missing mandatory parameter 'serviceName'
 134
 135 /services
 136 ~~~~~~~~~
 137
 138 GET
 139 +++
 140
 141 Query service information.
 142
 143 **URL path:**
 144   /services?name=<service-name>
 145
 146 **Parameters:**
 147   name: (*Optional*)
 148     The name of the service.
 149
 150 **Responses:**
 151   200:
 152         Array of JSON objects (ServiceStatus). ::
 153
 154          {
 155              "callbackUrl": "string",             (Callback URL)
 156              "keepAliveIntervalSeconds": 0,       (Policy keep alive interval)
 157              "serviceName": "string",             (Identity of the service)
 158              "timeSinceLastActivitySeconds": 0    (Time since last invocation by the service)
 159          }
 160   404:
 161         Service is not found.
 162
 163 **Examples:**
 164   **Call**: ::
 165
 166     curl -X GET "http://localhost:8081/services?name=existing"
 167
 168   Result:
 169     200: ::
 170
 171        [
 172          {
 173            "serviceName":"existing",
 174            "keepAliveIntervalSeconds":0,
 175            "timeSinceLastActivitySeconds":7224,
 176            "callbackUrl":"URL"
 177          }
 178       ]
 179
 180   **Call**: ::
 181
 182     curl -X GET "http://localhost:8081/services?name=nonexistent"
 183
 184   Result:
 185      404: ::
 186
 187        Service not found
 188
 189 DELETE
 190 ++++++
 191
 192 Delete a service.
 193
 194 **URL path:**
 195   /services?name=<service-name>
 196
 197 **Parameters:**
 198   name: (*Required*)
 199     The name of the service.
 200
 201 **Responses:**
 202   204:
 203         OK
 204   404:
 205         Service not found.
 206
 207 **Examples:**
 208   **Call**: ::
 209
 210     curl -X DELETE "http://localhost:8081/services?name=existing"
 211
 212   Result:
 213     204: ::
 214
 215        OK
 216
 217   **Call**: ::
 218
 219     curl -X DELETE "http://localhost:8081/services?name=nonexistent"
 220
 221   Result:
 222      404: ::
 223
 224        Could not find service: nonexistent
 225
 226 /services/keepalive
 227 ~~~~~~~~~~~~~~~~~~~
 228
 229 PUT
 230 +++
 231
 232 Heart beat from a service.
 233
 234 **URL path:**
 235   /services/keepalive?name=<service-name>
 236
 237 **Parameters:**
 238   name: (*Required*)
 239     The name of the service.
 240
 241 **Responses:**
 242   200:
 243         OK
 244   404:
 245         Service is not found.
 246
 247 **Examples:**
 248   **Call**: ::
 249
 250     curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
 251
 252   Result:
 253     200: ::
 254
 255        OK
 256
 257   **Call**: ::
 258
 259     curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
 260
 261   Result:
 262      404: ::
 263
 264        Could not find service: nonexistent
 265
 266 .. _policy-management:
 267
 268 Policy Management
 269 =================
 270
 271 Policies are based on types. The set of available policy types is determined by the set of policy types supported by
 272 Near |nbh| RT |nbsp| RICs. At startup, the Policy Agent queries all Near |nbh| RT |nbsp| RICs for their supported types
 273 and stores them in its internal repository. It then checks this at regular intervals to keep the repository of types up
 274 to date. Policy types cannot be created, updated or deleted using this interface since this must be done via the
 275 Near |nbh| RT |nbsp| RICs.
 276
 277 Policies can be queried, created, updated, and deleted. A policy is always created in a specific
 278 Near |nbh| RT |nbsp| RIC.
 279
 280 When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
 281 it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
 282 inconsistency, the Policy Agent will start a synchronization job and try to reflect the status of the
 283 Near |nbh| RT |nbsp| RIC. If this fails, the Policy Agent will delete all policies for the specific
 284 Near |nbh| RT |nbsp| RIC in the internal repository and set its state to *UNKNOWN*. This means that no interaction with
 285 the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent has been able to contact it again and re-synchronize its
 286 state in the repository.
 287
 288 Policy Types
 289 ------------
 290
 291 A policy type defines a name and a JSON schema that constrains the content of a policy of that type.
 292
 293 /policy_types
 294 ~~~~~~~~~~~~~
 295
 296 GET
 297 +++
 298
 299 Query policy type names.
 300
 301 **URL path:**
 302   /policy_types?ric=<name-of-ric>
 303
 304 **Parameters:**
 305   ric: (*Optional*)
 306     The name of the Near |nbh| RT |nbsp| RIC to get types for.
 307
 308 **Responses:**
 309
 310   200:
 311         Array of policy type names.
 312   404:
 313         Near |nbh| RT |nbsp| RIC is not found.
 314
 315 **Examples:**
 316   **Call**: ::
 317
 318     curl -X GET "http://localhost:8081/policy_types"
 319
 320   Result:
 321     200: ::
 322
 323        [
 324          "STD_PolicyModelUnconstrained_0.2.0",
 325          "Example_QoETarget_1.0.0",
 326          "ERIC_QoSNudging_0.2.0"
 327       ]
 328
 329   **Call**: ::
 330
 331     curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
 332
 333   Result:
 334      404: ::
 335
 336        org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
 337
 338 /policy_schema
 339 ~~~~~~~~~~~~~~
 340
 341 GET
 342 +++
 343
 344 Returns one policy type schema definition.
 345
 346 **URL path:**
 347   /policy_schema?id=<name-of-type>
 348
 349 **Parameters:**
 350   id: (*Required*)
 351     The ID of the policy type to get the definition for.
 352
 353 **Responses:**
 354   200:
 355         Policy schema as JSON schema.
 356   404:
 357         Policy type is not found.
 358
 359 **Examples:**
 360   **Call**: ::
 361
 362     curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
 363
 364   Result:
 365     200: ::
 366
 367       {
 368         "$schema": "http://json-schema.org/draft-07/schema#",
 369         "title": "STD_PolicyModelUnconstrained_0.2.0",
 370         "description": "Standard model of a policy with unconstrained scope id combinations",
 371         "type": "object",
 372         "properties": {
 373          "scope": {
 374             "type": "object",
 375             "properties": {
 376               "ueId": {"type": "string"},
 377               "groupId": {"type": "string"}
 378             },
 379             "minProperties": 1,
 380             "additionalProperties": false
 381           },
 382           "qosObjectives": {
 383             "type": "object",
 384             "properties": {
 385               "gfbr": {"type": "number"},
 386               "mfbr": {"type": "number"}
 387             },
 388             "additionalProperties": false
 389           },
 390           "resources": {
 391             "type": "array",
 392             "items": {
 393               "type": "object",
 394               "properties": {
 395                 "cellIdList": {
 396                   "type": "array",
 397                   "minItems": 1,
 398                   "uniqueItems": true,
 399                   "items": {
 400                     "type": "string"
 401                   }
 402                 },
 403               "additionalProperties": false,
 404               "required": ["cellIdList"]
 405             }
 406           }
 407         },
 408         "minProperties": 1,
 409         "additionalProperties": false,
 410         "required": ["scope"]
 411       }
 412
 413   **Call**: ::
 414
 415     curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
 416
 417   Result:
 418      404: ::
 419
 420        org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
 421
 422 /policy_schemas
 423 ~~~~~~~~~~~~~~~
 424
 425 GET
 426 +++
 427
 428 Returns policy type schema definitions.
 429
 430 **URL path:**
 431   /policy_schemas?ric=<name-of-ric>
 432
 433 **Parameters:**
 434   ric: (*Optional*)
 435     The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
 436
 437 **Responses:**
 438   200:
 439         An array of policy schemas as JSON schemas.
 440   404:
 441         Near |nbh| RT |nbsp| RIC is not found.
 442
 443 **Examples:**
 444   **Call**: ::
 445
 446     curl -X GET "http://localhost:8081/policy_schemas"
 447
 448   Result:
 449     200: ::
 450
 451       [{
 452         "$schema": "http://json-schema.org/draft-07/schema#",
 453         "title": "STD_PolicyModelUnconstrained_0.2.0",
 454         "description": "Standard model of a policy with unconstrained scope id combinations",
 455         "type": "object",
 456         "properties": {
 457          "scope": {
 458             "type": "object",
 459             .
 460             .
 461             .
 462         "additionalProperties": false,
 463         "required": ["scope"]
 464       },
 465        .
 466        .
 467        .
 468       {
 469         "$schema": "http://json-schema.org/draft-07/schema#",
 470         "title": "Example_QoETarget_1.0.0",
 471         "description": "Example QoE Target policy type",
 472         "type": "object",
 473         "properties": {
 474          "scope": {
 475             "type": "object",
 476             .
 477             .
 478             .
 479         "additionalProperties": false,
 480         "required": ["scope"]
 481       }]
 482
 483   **Call**: ::
 484
 485     curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
 486
 487   Result:
 488      404: ::
 489
 490        org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
 491
 492 Policy
 493 ------
 494
 495 A policy is defined by its type schema.
 496
 497 Once a service has created a policy, it is the service's responsibility to maintain its life cycle. Since policies are
 498 transient, they will not survive a restart of a Near |nbh| RT |nbsp| RIC. But this is handled by the Policy Agent. When
 499 a Near |nbh| RT |nbsp| RIC has been restarted, the Policy Agent will try to recreate the policies in the
 500 Near |nbh| RT |nbsp| RIC that are stored in its local repository. This means that the service always must delete any
 501 policy it has created. There are only two exceptions, see below:
 502
 503 - The service has registered a "*Keep Alive Interval*", then its policies will be deleted if it fails to notify the
 504   Policy Agent in due time.
 505 - The Policy Agent completely fails to synchronize with a Near |nbh| RT |nbsp| RIC.
 506
 507 /policies
 508 ~~~~~~~~~
 509
 510 GET
 511 +++
 512
 513 Query policies.
 514
 515 **URL path:**
 516   /policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
 517
 518 **Parameters:**
 519   ric: (*Optional*)
 520     The name of the Near |nbh| RT |nbsp| RIC to get policies for.
 521   service: (*Optional*)
 522     The name of the service to get policies for.
 523   type: (*Optional*)
 524     The name of the policy type to get policies for.
 525
 526 **Responses:**
 527   200:
 528         Array of JSON objects (PolicyInfo). ::
 529
 530           {
 531             "id": "string",              (Identity of the policy)
 532             "json": "object",            (The configuration of the policy)
 533             "lastModified": "string",    (Timestamp, last modification time)
 534             "ric": "string",             (Identity of the target Near |nbh| RT |nbsp| RIC)
 535             "service": "string",         (The name of the service owning the policy)
 536             "type": "string"             (Name of the policy type)
 537           }
 538   404:
 539         Near |nbh| RT |nbsp| RIC or policy type not found.
 540
 541 **Examples:**
 542   **Call**: ::
 543
 544     curl -X GET "http://localhost:8081/policies?ric=existing"
 545
 546   Result:
 547     200: ::
 548
 549        [
 550          {
 551            "id": "Policy 1",
 552            "json": {
 553              "scope": {
 554                "ueId": "UE 1",
 555                "groupId": "Group 1"
 556              },
 557              "qosObjectives": {
 558                "gfbr": 1,
 559                "mfbr": 2
 560              },
 561              "cellId": "Cell 1"
 562            },
 563            "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
 564            "ric": "existing",
 565            "service": "Service 1",
 566            "type": "STD_PolicyModelUnconstrained_0.2.0"
 567          },
 568          {
 569            "id": "Policy 2",
 570            "json": {
 571                .
 572                .
 573                .
 574            },
 575            "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
 576            "ric": "existing",
 577            "service": "Service 2",
 578            "type": "Example_QoETarget_1.0.0"
 579          }
 580       ]
 581
 582   **Call**: ::
 583
 584     curl -X GET "http://localhost:8081/policies?type=nonexistent"
 585
 586   Result:
 587      404: ::
 588
 589        Policy type not found
 590
 591 /policy
 592 ~~~~~~~
 593
 594 GET
 595 +++
 596
 597 Returns a policy configuration.
 598
 599 **URL path:**
 600   /policy?id=<policy-id>
 601
 602 **Parameters:**
 603   id: (*Required*)
 604     The ID of the policy instance.
 605
 606 **Responses:**
 607   200:
 608         JSON object containing policy information. ::
 609
 610           {
 611             "id": "string",                  (ID of policy)
 612             "json": "object",                (JSON with policy data speified by the type)
 613             "ownerServiceName": "string",    (Name of the service that created the policy)
 614             "ric": "string",                 (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
 615             "type": "string",                (Name of the policy type of the policy)
 616             "lastModified"                   (Timestamp, last modification time)
 617           }
 618   404:
 619         Policy is not found.
 620
 621 **Examples:**
 622   **Call**: ::
 623
 624     curl -X GET "http://localhost:8081/policy?id=Policy 1"
 625
 626   Result:
 627     200: ::
 628
 629        {
 630          "id": "Policy 1",
 631          "json", {
 632            "scope": {
 633              "ueId": "UE1 ",
 634              "cellId": "Cell 1"
 635            },
 636            "qosObjectives": {
 637              "gfbr": 319.5,
 638              "mfbr": 782.75,
 639              "priorityLevel": 268.5,
 640              "pdb": 44.0
 641            },
 642            "qoeObjectives": {
 643              "qoeScore": 329.0,
 644              "initialBuffering": 27.75,
 645              "reBuffFreq": 539.0,
 646              "stallRatio": 343.0
 647            },
 648            "resources": []
 649          },
 650          "ownerServiceName": "Service 1",
 651          "ric": "ric1",
 652          "type": "STD_PolicyModelUnconstrained_0.2.0",
 653          "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
 654        }
 655
 656   **Call**: ::
 657
 658     curl -X GET "http://localhost:8081/policy?id=nonexistent"
 659
 660   Result:
 661      404: ::
 662
 663        Policy is not found
 664
 665 PUT
 666 +++
 667
 668 Create/Update a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
 669 "*Keep Alive Interval*" registered.
 670
 671 **URL path:**
 672   /policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
 673
 674 **Parameters:**
 675   id: (*Required*)
 676     The ID of the policy instance.
 677   ric: (*Required*)
 678     The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
 679   service: (*Required*)
 680     The name of the service creating the policy.
 681   type: (*Optional*)
 682     The name of the policy type.
 683
 684 **Body:** (*Required*)
 685     A JSON object containing the data specified by the type.
 686
 687 **Responses:**
 688   200:
 689         Policy updated.
 690   201:
 691         Policy created.
 692   404:
 693         Near |nbh| RT |nbsp| RIC or policy type is not found.
 694   423:
 695         Near |nbh| RT |nbsp| RIC is not operational.
 696
 697 **Examples:**
 698   **Call**: ::
 699
 700     curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 701       -H  "Content-Type: application/json"
 702       -d '{
 703             "scope": {
 704               "ueId": "UE 1",
 705               "cellId": "Cell 1"
 706             },
 707             "qosObjectives": {
 708               "gfbr": 319.5,
 709               "mfbr": 782.75,
 710               "priorityLevel": 268.5,
 711               "pdb": 44.0
 712             },
 713             "qoeObjectives": {
 714               "qoeScore": 329.0,
 715               "initialBuffering": 27.75,
 716               "reBuffFreq": 539.0,
 717               "stallRatio": 343.0
 718             },
 719             "resources": []
 720           }'
 721
 722   Result:
 723     200
 724
 725 DELETE
 726 ++++++
 727
 728 Deletes a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
 729 "*Keep Alive Interval*" registered.
 730
 731 **URL path:**
 732   /policy?id=<policy-id>
 733
 734 **Parameters:**
 735   id: (*Required*)
 736     The ID of the policy instance.
 737
 738 **Responses:**
 739   204:
 740         Policy deleted.
 741   404:
 742         Policy is not found.
 743   423:
 744         Near |nbh| RT |nbsp| RIC is not operational.
 745
 746 **Examples:**
 747   **Call**: ::
 748
 749     curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
 750
 751   Result:
 752     204
 753
 754 /policy_ids
 755 ~~~~~~~~~~~
 756
 757 GET
 758 +++
 759
 760 Query policy type IDs.
 761
 762 **URL path:**
 763   /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
 764
 765 **Parameters:**
 766   ric: (*Optional*)
 767     The name of the Near |nbh| RT |nbsp| RIC to get policies for.
 768   service: (*Optional*)
 769     The name of the service to get policies for.
 770   type: (*Optional*)
 771     The name of the policy type to get policies for.
 772
 773 **Responses:**
 774   200:
 775         Array of policy type names.
 776   404:
 777         RIC or policy type not found.
 778
 779 **Examples:**
 780   **Call**: ::
 781
 782     curl -X GET "http://localhost:8081/policy_ids"
 783
 784   Result:
 785     200: ::
 786
 787        [
 788          "Policy 1",
 789          "Policy 2",
 790          "Policy 3"
 791       ]
 792
 793   **Call**: ::
 794
 795     curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
 796
 797   Result:
 798      404: ::
 799
 800        Ric not found
 801
 802 /policy_status
 803 ~~~~~~~~~~~~~~
 804
 805 GET
 806 +++
 807
 808 Returns the status of a policy.
 809
 810 **URL path:**
 811   /policy_status?id=<policy-id>
 812
 813 **Parameters:**
 814   id: (*Required*)
 815     The ID of the policy.
 816
 817 **Responses:**
 818   200:
 819         JSON object with policy status.
 820   404:
 821         Policy not found.
 822
 823 Near-RT RIC Repository
 824 ======================
 825
 826 The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
 827 find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
 828 Near |nbh| RT |nbsp| RICs that support a specific policy type.
 829
 830 Near-RT RIC
 831 -----------
 832
 833 /ric
 834 ~~~~
 835
 836 GET
 837 +++
 838
 839 Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
 840
 841  **URL path:**
 842   /ric?managedElementId=<id-of-managed-element>
 843
 844 **Parameters:**
 845   managedElementId: (*Required*)
 846     The ID of the Managed Element.
 847
 848 **Responses:**
 849   200:
 850         Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
 851   404:
 852         No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
 853
 854 **Examples:**
 855   **Call**: ::
 856
 857     curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
 858
 859   Result:
 860     200: ::
 861
 862       Ric 1
 863
 864   **Call**: ::
 865
 866     curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
 867
 868   Result:
 869      404
 870
 871 /rics
 872 ~~~~~
 873
 874 GET
 875 +++
 876
 877 Query Near |nbh| RT |nbsp| RIC information.
 878
 879  **URL path:**
 880   /rics?policyType=<name-of-policy-type>
 881
 882 **Parameters:**
 883   policyType: (*Optional*)
 884     The name of the policy type.
 885
 886 **Responses:**
 887   200:
 888         Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
 889
 890           [
 891             {
 892               "managedElementIds": [
 893                 "string"
 894               ],
 895               "policyTypes": [
 896                 "string"
 897               ],
 898               "ricName": "string",
 899               "state": "string"
 900             }
 901           ]
 902   404:
 903         Policy type is not found.
 904
 905 **Examples:**
 906   **Call**: ::
 907
 908     curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
 909
 910   Result:
 911     200: ::
 912
 913       [
 914         {
 915           "managedElementIds": [
 916             "ME 1",
 917             "ME 2"
 918           ],
 919           "policyTypes": [
 920             "STD_PolicyModelUnconstrained_0.2.0",
 921             "Example_QoETarget_1.0.0",
 922             "ERIC_QoSNudging_0.2.0"
 923           ],
 924           "ricName": "Ric 1",
 925           "state": "AVAILABLE"
 926         },
 927           .
 928           .
 929           .
 930         {
 931           "managedElementIds": [
 932             "ME 3"
 933           ],
 934           "policyTypes": [
 935             "STD_PolicyModelUnconstrained_0.2.0"
 936           ],
 937           "ricName": "Ric X",
 938           "state": "UNAVAILABLE"
 939         }
 940       ]
 941
 942   **Call**: ::
 943
 944     curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
 945
 946   Result:
 947      404: ::
 948
 949       Policy type not found
 950
 951 Health Check
 952 ============
 953
 954 The status of the Policy Agent.
 955
 956 Health Check
 957 ------------
 958
 959 /status
 960 ~~~~~~~
 961
 962 GET
 963 +++
 964
 965 Returns the status of the Policy Agent.
 966
 967  **URL path:**
 968   /status
 969
 970 **Parameters:**
 971   None.
 972
 973 **Responses:**
 974   200:
 975         Service is living.
 976
 977 **Examples:**
 978   **Call**: ::
 979
 980     curl -X GET "http://localhost:8081/status"
 981
 982   Result:
 983     200
 984
 985 ****************
 986 A1 through DMaaP
 987 ****************
 988
 989 The Policy Agent also provides the possibility to use DMaap to handle policies according to the A1 specification. The
 990 Policy Agent polls the DMaaP Message Router regularly and processes any messages targeted to it. The response is then
 991 published back to the DMaaP Message Router with the result of the call.
 992
 993 Send Message
 994 ============
 995
 996 The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
 997 :ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
 998 Agent. The "*operation*" can be one of the following: "*GET | PUT | POST | DELETE*". ::
 999
1000   {
1001     "type": "string",
1002     "correlationId": "string",
1003     "target": "string",
1004     "timestamp": "timestamp",
1005     "apiVersion": "string",
1006     "originatorId": "string",
1007     "requestId": "string",
1008     "operation": "string",
1009     "url": "string"
1010   }
1011
1012 Example
1013 -------
1014
1015 To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
1016 Router: ::
1017
1018   {
1019     "type":"request",
1020     "correlationId":"c09ac7d1-de62-0016-2000-e63701125557-201",
1021     "target":"policy-agent",
1022     "timestamp":"2019-05-14T11:44:51.36Z",
1023     "apiVersion":"1.0",
1024     "originatorId":"849e6c6b420",
1025     "requestId":"23343221",
1026     "operation":"GET",
1027     "url":"/policy_schemas?ric=ric_ric-simulator_1"
1028   }
1029
1030 Receive Message
1031 ===============
1032
1033 The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
1034 "*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
1035
1036   {
1037     "requestId": "string",
1038     "correlationId": "string",
1039     "originatorId": "string",
1040     "type": "string",
1041     "message": "string",
1042     "type":  string",
1043     "timestamp": "string",
1044     "status": "string"
1045   }
1046
1047 Example
1048 -------
1049
1050 The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
1051 the Policy Agent: ::
1052
1053   {
1054     \"requestId\":\"23343221\",
1055     \"correlationId\":\"c09ac7d1-de62-0016-2000-e63701125557-201\",
1056     \"originatorId\":\"849e6c6b420\",
1057     \"type\":\"response\",
1058     \"message\":\"[
1059       {
1060       \\\"$schema\\\":\\\"http://json-schema.org/draft-07/schema#\\\",
1061       \\\"description\\\":\\\"QoS policy type\\\",
1062       \\\"title\\\":\\\"STD_QoSNudging_0.2.0\\\",
1063       \\\"type\\\":\\\"object\\\",
1064       \\\"properties\\\":{\\\"scope\\\":{\\\"additionalProperties\\\":true,
1065       \\\"type\\\":\\\"object\\\",
1066       \\\"properties\\\":{\\\"qosId\\\":{\\\"type\\\":\\\"string\\\"},
1067       \\\"ueId\\\":{\\\"type\\\":\\\"string\\\"}},
1068       \\\"required\\\":[\\\"ueId\\\",
1069       \\\"qosId\\\"]},
1070       \\\"statement\\\":{\\\"additionalProperties\\\":false,
1071       \\\"type\\\":\\\"object\\\",
1072       \\\"properties\\\":{\\\"priorityLevel\\\":{\\\"type\\\":\\\"number\\\"}},
1073       \\\"required\\\":[\\\"priorityLevel\\\"]}}
1074       }
1075     ]\",
1076     \"timestamp\":\"2019-05-14T11:44:51.36Z\",
1077     \"status\":\"200 OK\"
1078   }