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