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           Something went wrong with the service registration.
 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 POST
 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 POST "http://localhost:8081/services/keepalive?name=existing"
 272
 273     Result:
 274       200: ::
 275
 276          OK
 277
 278     Call: ::
 279
 280       curl -X POST "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?instance=<name-of-policy>
 638
 639   **Parameters:**
 640
 641     instance: (*Required*)
 642       The ID/name of the policy instance.
 643
 644   **Responses:**
 645
 646     200:
 647           JSON object containing policy information. ::
 648
 649             {
 650               "id": "string",                  (ID/name 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?instance=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?instance=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?instance=<name-of-policy>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
 714
 715   **Parameters:**
 716
 717     instance: (*Required*)
 718       The ID/name 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 locked.
 745
 746   **Examples:**
 747
 748     Call: ::
 749
 750       curl -X PUT "http://localhost:8081/policy?instance=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?instance=<name-of-policy>
 783
 784   **Parameters:**
 785
 786     instance: (*Required*)
 787       The ID/name of the policy instance.
 788
 789   **Responses:**
 790
 791     204:
 792           Policy deleted.
 793
 794     404:
 795           Policy is not found.
 796
 797   **Examples:**
 798
 799     Call: ::
 800
 801       curl -X DELETE "http://localhost:8081/policy?instance=Policy 1"
 802
 803     Result:
 804       204
 805
 806 /policy_ids
 807 ~~~~~~~~~~~
 808
 809 GET
 810 +++
 811
 812   Query policy type IDs.
 813
 814   **URL path:**
 815     /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
 816
 817   **Parameters:**
 818
 819     ric: (*Optional*)
 820       The name of the Near |nbh| RT |nbsp| RIC to get policies for.
 821
 822     service: (*Optional*)
 823       The name of the service to get policies for.
 824
 825     type: (*Optional*)
 826       The name of the policy type to get policies for.
 827
 828   **Responses:**
 829
 830     200:
 831           Array of policy type names.
 832
 833     404:
 834           RIC or policy type not found.
 835
 836   **Examples:**
 837
 838     Call: ::
 839
 840       curl -X GET "http://localhost:8081/policy_ids"
 841
 842     Result:
 843       200: ::
 844
 845          [
 846            "Policy 1",
 847            "Policy 2",
 848            "Policy 3"
 849         ]
 850
 851     Call: ::
 852
 853       curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
 854
 855     Result:
 856        404: ::
 857
 858          Ric not found
 859
 860 /policy_status
 861 ~~~~~~~~~~~~~~
 862
 863 GET
 864 +++
 865
 866   Returns the status of a policy.
 867
 868   **URL path:**
 869     /policy_status?instance=<name-of-policy>
 870
 871   **Parameters:**
 872
 873     instance: (*Required*)
 874       The ID/name of the policy.
 875
 876   **Responses:**
 877
 878     200:
 879           JSON object with policy status.
 880
 881     404:
 882           Policy not found.
 883
 884 Near-RT RIC Repository
 885 ======================
 886
 887 The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
 888 find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
 889 Near |nbh| RT |nbsp| RICs that support a specific policy type.
 890
 891 Near-RT RIC
 892 -----------
 893
 894 /ric
 895 ~~~~
 896
 897 GET
 898 +++
 899
 900   Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
 901
 902    **URL path:**
 903     /ric?managedElementId=<id-of-managed-element>
 904
 905   **Parameters:**
 906
 907     managedElementId: (*Optional*)
 908       The ID of the Managed Element.
 909
 910   **Responses:**
 911
 912     200:
 913           Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
 914
 915     404:
 916           No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
 917
 918   **Examples:**
 919
 920     Call: ::
 921
 922       curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
 923
 924     Result:
 925       200: ::
 926
 927         Ric 1
 928
 929     Call: ::
 930
 931       curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
 932
 933     Result:
 934        404
 935
 936 /rics
 937 ~~~~~
 938
 939 GET
 940 +++
 941
 942   Query Near |nbh| RT |nbsp| RIC information.
 943
 944    **URL path:**
 945     /rics?policyType=<name-of-policy-type>
 946
 947   **Parameters:**
 948
 949     policyType: (*Optional*)
 950       The name of the policy type.
 951
 952   **Responses:**
 953
 954     200:
 955           Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
 956
 957             [
 958               {
 959                 "managedElementIds": [
 960                   "string"
 961                 ],
 962                 "policyTypes": [
 963                   "string"
 964                 ],
 965                 "ricName": "string"
 966               }
 967             ]
 968
 969     404:
 970           Policy type is not found.
 971
 972   **Examples:**
 973
 974     Call: ::
 975
 976       curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
 977
 978     Result:
 979       200: ::
 980
 981         [
 982           {
 983             "managedElementIds": [
 984               "ME 1",
 985               "ME 2"
 986             ],
 987             "policyTypes": [
 988               "STD_PolicyModelUnconstrained_0.2.0",
 989               "Example_QoETarget_1.0.0",
 990               "ERIC_QoSNudging_0.2.0"
 991             ],
 992             "ricName": "Ric 1"
 993           },
 994             .
 995             .
 996             .
 997           {
 998             "managedElementIds": [
 999               "ME 3"
1000             ],
1001             "policyTypes": [
1002               "STD_PolicyModelUnconstrained_0.2.0"
1003             ],
1004             "ricName": "Ric X"
1005           }
1006         ]
1007
1008     Call: ::
1009
1010       curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
1011
1012     Result:
1013        404: ::
1014
1015         Policy type not found
1016
1017 Health Check
1018 ============
1019
1020 The status of the Policy Agent.
1021
1022 Health Check
1023 ------------
1024
1025 /status
1026 ~~~~~~~
1027
1028 GET
1029 +++
1030
1031   Returns the status of the Policy Agent.
1032
1033    **URL path:**
1034     /status
1035
1036   **Parameters:**
1037
1038     None.
1039
1040   **Responses:**
1041
1042     200:
1043           Service is living.
1044
1045   **Examples:**
1046
1047     Call: ::
1048
1049       curl -X GET "http://localhost:8081/status"
1050
1051     Result:
1052       200
1053
1054 ****************
1055 A1 through DMaaP
1056 ****************
1057
1058 The Policy Agent also provides the possibility to use DMaap to handle policies according to the A1 specification. The
1059 Policy Agent polls the DMaaP Message Router regularly and processes any messages targeted to it. The response is then
1060 published back to the DMaaP Message Router with the result of the call.
1061
1062 Send Message
1063 ============
1064
1065 The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
1066 :ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
1067 Agent. The "*operation*" can be one of the following: "*GET | PUT | POST | DELETE*". ::
1068
1069   {
1070     "type": "string",
1071     "correlationId": "string",
1072     "target": "string",
1073     "timestamp": "timestamp",
1074     "apiVersion": "string",
1075     "originatorId": "string",
1076     "requestId": "string",
1077     "operation": "string",
1078     "url": "string"
1079   }
1080
1081 Example
1082 -------
1083
1084 To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
1085 Router: ::
1086
1087   {
1088     "type":"request",
1089     "correlationId":"c09ac7d1-de62-0016-2000-e63701125557-201",
1090     "target":"policy-agent",
1091     "timestamp":"2019-05-14T11:44:51.36Z",
1092     "apiVersion":"1.0",
1093     "originatorId":"849e6c6b420",
1094     "requestId":"23343221",
1095     "operation":"GET",
1096     "url":"/policy_schemas?ric=ric_ric-simulator_1"
1097   }
1098
1099 Receive Message
1100 ===============
1101
1102 The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
1103 "*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
1104
1105   {
1106     "requestId": "string",
1107     "correlationId": "string",
1108     "originatorId": "string",
1109     "type": "string",
1110     "message": "string",
1111     "type":  string",
1112     "timestamp": "string",
1113     "status": "string"
1114   }
1115
1116 Example
1117 -------
1118
1119 The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
1120 the Policy Agent: ::
1121
1122   {
1123     \"requestId\":\"23343221\",
1124     \"correlationId\":\"c09ac7d1-de62-0016-2000-e63701125557-201\",
1125     \"originatorId\":\"849e6c6b420\",
1126     \"type\":\"response\",
1127     \"message\":\"[
1128       {
1129       \\\"$schema\\\":\\\"http://json-schema.org/draft-07/schema#\\\",
1130       \\\"description\\\":\\\"QoS policy type\\\",
1131       \\\"title\\\":\\\"STD_QoSNudging_0.2.0\\\",
1132       \\\"type\\\":\\\"object\\\",
1133       \\\"properties\\\":{\\\"scope\\\":{\\\"additionalProperties\\\":true,
1134       \\\"type\\\":\\\"object\\\",
1135       \\\"properties\\\":{\\\"qosId\\\":{\\\"type\\\":\\\"string\\\"},
1136       \\\"ueId\\\":{\\\"type\\\":\\\"string\\\"}},
1137       \\\"required\\\":[\\\"ueId\\\",
1138       \\\"qosId\\\"]},
1139       \\\"statement\\\":{\\\"additionalProperties\\\":false,
1140       \\\"type\\\":\\\"object\\\",
1141       \\\"properties\\\":{\\\"priorityLevel\\\":{\\\"type\\\":\\\"number\\\"}},
1142       \\\"required\\\":[\\\"priorityLevel\\\"]}}
1143       }
1144     ]\",
1145     \"timestamp\":\"2019-05-14T11:44:51.36Z\",
1146     \"status\":\"200 OK\"
1147   }