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