A1 Interface Simulator¶

A1 Simulator Overview¶

The A1 Simulator terminates the A1 interface and provides a way to test Non-RT RIC services without the need to deploy Near‑RT RICs.

Apart from providing the A1 API, the simulator also provides an administrative API to manage policy types and manipulate the simulator, see “Simulator API”.

The A1 Simulator supports running multiple simulations using different versions of the A1 Application protocol, and supports realistic stateful simulation of A1 Enrichment Information and A1 Policy behaviours.

For information on how to run the simulator, see the README.md file in the repository.

Simulator API¶

This document describes the API used to manage policy types and manipulate the simulator.

The simulator supports different versions of the A1 interface. Some functions are common for all versions, and some are specific for a certain version.

Common Functions¶

Health Check¶

The status of the simulator.

/¶

GET¶

Returns the status of the simulator.

URL path:

/

Parameters:

None.

Responses:

200:: OK

Examples:

Call:

curl -X GET "http://localhost:8085/"

Result:

200:

OK

Supported Interfaces¶

The simulator can support different versions of the A1 interface. With this API the supported versions can be listed.

/container_interfaces¶

GET¶

Returns the status of the simulator. (Not available for A1 Standard 1.1.3)

URL path:

/container_interfaces

Parameters:

None.

Responses:

200:: List of supported interfaces.

Examples:

Call:

curl -X GET "http://localhost:8085/container_interfaces"

Result:

200:

Current interface: STD_2.0.0  All supported A1 interface yamls in this container: ['OSC_2.1.0', 'STD_1.1.3', 'STD_2.0.0']

Counters¶

The simulator keeps counts of different things that can be accessed.

/counter¶

GET¶

Get a counter. Counter-name can be one of the following: ‘num_instances’, ‘num_types’, ‘interface’, ‘remote_hosts’ or ‘datadelivery’.

URL path:

/counter/{counter-name}

Parameters:

None.

Responses:

200:

The counter value for the given counter.

Examples:

Call:

curl -X GET "http://localhost:8085/counter/num_instances"

Result:

200:

Reset simulator¶

There are two ways to reset the simulator, delete all instances or make a complete reset which resets the simulator to its original state.

/deleteinstances¶

POST¶

Delete all policy instances.

URL path:

/deleteinstances

Parameters:

None.

Responses:

200:

All policy instances deleted.

Examples:

Call:

curl -X POST "http://localhost:8085/deleteinstances"

Result:

200:

All policy instances deleted.

/deleteall¶

POST¶

Full reset.

URL path:

/deleteall

Parameters:

None.

Responses:

200:

All policy instances and types deleted.

Examples:

Call:

curl -X POST "http://localhost:8085/deleteall"

Result:

200:

All policy instances and types deleted.

200 ::: All policy instances deleted (Only for STD_1.1.3 since it has no types)

Response manipulation¶

It is possible to manipulate the response of all operations on the A1 interface (admin interface is not affected)

/forceresponse¶

POST¶

Force a specific response code for one (the next) A1 operation. After that response, the reponse code will go back to normal.

URL path:

/forceresponse?code=<http-response-code>

Parameters:

code: (Required)

The HTTP response code to return.

Responses:

200:

Force response code: <expected code> set for one single A1 response

Examples:

Call:

curl -X POST "http://localhost:8085/forceresponse?code=400"

Result:

200:

Force response code:  400 set for one single A1 response

/forcedelay¶

POST¶

Force delayed response of all A1 responses. The setting will remain until the delay is set to ‘0’

URL path:

/forcedelay?delay=<delay-time-seconds>

Parameters:

delay: (Required)

The time in seconds to delay all responses.

Responses:

200:

Force delay: <expected delay> sec set for all A1 responses

Examples:

Call:

curl -X POST "http://localhost:8085/forcedelay?delay=2"

Result:

200:

Force delay: 2 sec set for all A1 responses

Configure logging¶

Detailed logging of the http headers and payload are activated by default. However, it is possible to turn this logging on or off. The ‘off’ state will only logg ip, url and respose code.

/payload_logging/¶

POST¶

Configure detailed logging on or off URL path:

/payload_logging/<state>

Parameters:

state: (Required)

The state, ‘on’ or ‘off’.

Responses:

200:

Force delay: <expected delay> sec set for all A1 responses

Examples:

Call:

curl -X POST "http://localhost:8085/payload_logging/on"

Result:

200:

Payload and header logging set to: on

Version Specific Functions¶

The methods available to control the simulator depends on the version of the A1 API the simulator is simulating.

OSC_2.1.0¶

This section describes the available administrative functions for the OSC_2.1.0 version of A1.

To see the A1 functions for this version, see OSC_2.1.0 API.

/policytype¶

PUT¶

Create a policy type.

URL path:

/policytype?id=<policy-type-id>

Parameters:

id: (Required)

The ID of the policy type.

Body: (Required)

A JSON object containing the schema for the type.

Responses:

200:

Policy type <policy-type-id> is OK.

201:

Policy type <policy-type-id> is OK.

Examples:

Call:

curl -X PUT "http://localhost:8085/policytype?id=1"
  -H  "Content-Type: application/json"
  -d '{
      "name": "pt1",
      "description": "pt1 policy type",
      "policy_type_id": 1,
      "create_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "STD_QoSNudging_0.2.0",
        "description": "QoS policy type",
        "type": "object",
        "properties": {
          "scope": {
            "type": "object",
            "properties": {
              "ueId": {
                "type": "string"
              },
              "qosId": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "ueId",
              "qosId"
            ]
          },
          "statement": {
            "type": "object",
            "properties": {
              "priorityLevel": {
                "type": "number"
              }
            },
            "additionalProperties": false,
            "required": [
              "priorityLevel"
            ]
          }
        }
      }
    }'

Result:

201:

Policy type 1 is OK

DELETE¶

Delete a policy type.

URL path:

/policytype?id=<policy-type-id>

Parameters:

id: (Required)

The ID of the policy type.

Responses:

204:

Policy type <policy-type-id> is OK.

Examples:

Call:

curl -X DELETE "http://localhost:8085/policytype?id=1"

Result:

204

/policytypes¶

GET¶

Get a list of policy types.

URL path:

/policytypes

Parameters:

None.

Responses:

200:

A list of policy types.

Examples:

Call:

curl -X GET "http://localhost:8085/policytypes"

Result:

200:

["1"]

/status¶

PUT¶

Set status and optional reason, delete and time stamp.

URL path:

/status?policyid=<policyid>&status=<status>&deleted=<value>&created_at=<time-stamp>

Parameters:

policyid: (Required)

The ID of a policy.

status: (Required)

The status of a policy.

deleted: (Optional)

True or false for real values, but accepts anything for error testing.

created_at: (Optional)

Time stamp for the status.

Responses:

200:

Status set to <status> for policy <policy-id>

Examples:

Call:

curl -X PUT "http://localhost:8085/status?policyid=1&status=Accepted"

Result:

200:

Status set to Accepted for policy Policy1.

A1 Standard 1.1.3¶

This section describes the available administrative functions for the A1 Standard 1.1.3 version of A1.

To see the A1 functions for this version, see A1 Standard 1.1.3 API.

/status¶

PUT¶

Set status and optional reason, delete and time stamp.

URL path:

/status?policyid=<policyid>&status=<status>&reason=<reason>

Parameters:

policyid: (Required)

The ID of a policy.

status: (Required)

The status of a policy.

reason: (Optional)

The reason for the status.

Responses:

200:

Status set to <status> for policy <policy-id>

Examples:

Call:

curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted"

Result:

200:

Status set to Accepted for policy Policy1

/sendstatus¶

POST¶

Send status for policy.

URL path:

/sendstatus?policyid=<policy-id>

Parameters:

policyid: (Required)

The ID of the policy to send status for.

Responses:

200:

Is a JSON with the response of the actual post request to the callback server, whatever that is.

Examples:

Call:

curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2"

Result:

200

A1 Standard 2.0.0¶

This section describes the available administrative functions for the A1 Standard 2.0.0 version of A1.

To see the A1 functions for this version, see A1 Standard 2.0.0 API.

/policytype¶

PUT¶

Create or update a policy type.

URL path:

/policytype?id={policy-type-id}

Parameters:

policy-type-id: (Required)

The ID of the policy type.

Body: (Required)

A JSON object containing the schema for the type.

Responses:

200:

The policy type <policy-type-id> is ok

201:

The policy type <policy-type-id> is ok

Examples:

Call:

curl -X PUT "http://localhost:8085/policytype?id=STD_PolicyModelUnconstrained_0.2.0"
  -H  "Content-Type: application/json"
  -d '{
        "policySchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "title": "STD_1_0.2.0",
          "description": "STD 1 policy type",
          "type": "object",
          "properties": {
            "scope": {
              "type": "object",
              "properties": {
                "ueId": {
                  "type": "string"
                },
                "qosId": {
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "ueId",
                "qosId"
              ]
            },
            "statement": {
              "type": "object",
              "properties": {
                "priorityLevel": {
                  "type": "number"
                }
              },
              "additionalProperties": false,
              "required": [
                "priorityLevel"
              ]
            }
          }
        },
        "statusSchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "title": "STD_1_0.2.0",
          "description": "STD 1 policy type status",
          "type": "object",
          "properties": {
            "enforceStatus": {
              "type": "string"
            },
            "enforceReason": {
              "type": "string"
            },
            "additionalProperties": false,
            "required": [
              "enforceStatus"
            ]
          }
        }
      }'

Result:

200:

Policy type STD_PolicyModelUnconstrained_0.2.0 is OK

201:

Policy type STD_PolicyModelUnconstrained_0.2.0 is OK

DELETE¶

Delete a policy type.

URL path:

/policytype?id={policy-type-id}

Parameters:

None.

Responses:

204

Examples:

Call:

curl -X DELETE "http://localhost:8085/policytype?id=STD_PolicyModelUnconstrained_0.2.0"

Result:

204

/policytypes¶

GET¶

Get a list of policy types.

URL path:

/policytypes

Parameters:

None.

Responses:

200:

A list of policy types.

Examples:

Call:

curl -X GET "http://localhost:8085/policytypes"

Result:

200:

["STD_PolicyModelUnconstrained_0.2.0"]

/{policyId}/{enforceStatus}¶

PUT¶

Set a status to a policy instance with an enforceStatus parameter only.

URL path:

/status?policyid={policyId}&status={status}&reason={reason}

Parameters:

None.

Responses:

200:

Status updated for policy: <policyId>

Examples:

Call:

curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=ENFORCED"

Result:

200:

Status updated for policy: Policy1

/{policyId}/{enforceStatus}/{enforceReason}¶

/sendstatus¶

POST¶

Send status for policy.

URL path:

/sendstatus?policyid=<policy-id>

Parameters:

policyid: (Required)

The ID of the policy to send status for.

Responses:

200:

Is a JSON with the response of the actual post request to the callback server, whatever that is.

Examples:

Call:

curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2"

Result:

200

Callout Server¶

API Documentation¶

The O-RAN SC external call-out server allows behavioral extensions to be added to the A1 Simulator. It creates an external call-out server, which provides a RESTful API. A1 Policy operations, for some A1 Policy Types, can then be redirected to the external call-out server, supporting supplemental simulator behavior for those A1 Policy Types.

Note: call-out server functionality is only available for ‘STD_2.0.0’ version simulators.

The external call-out server exposes a ‘Callout server API’ REST API. This internal API is invoked directly by the A1 Simulator, and is not intended to be used by any other client. The ‘Callout Server API’ is documented in Callout Server API and in OpenAPI YAML format:

API name
Callout Server API	`link`

External call-out servers also expose an ‘Admin API’ to manipulate the behavior of the call-out server itself. The ‘Callout Server Admin API’ is documented below:

Admin Functions¶

Health Check¶

GET¶

Returns the status of the external server.

URL path:

/

Parameters:

None.

Responses:

200:: OK

Examples:

Call:

curl -X GET "http://localhost:9095/"

Result:

200:

OK

Delete all policy instances in external server¶

POST¶

Delete all policy instances.

URL path:

/serveradmin/deleteinstances

Parameters:

None.

Responses:

200:

All a1 policy instances deleted

Examples:

Call:

curl -X POST "http://localhost:9095/serveradmin/deleteinstances"

Result:

200:

All a1 policy instances deleted

Response manipulation¶

It is possible to manipulate the response of all operations on the external server

POST¶

Force a specific response code for the all (the next) external server operation. Unless it is reset, it will always respond the same response code back.

URL path:

/serveradmin/forceresponse?code=<http-response-code>

Parameters:

code: (Required)

The HTTP response code to return.

Responses:

200:

Force response code: <expected code> set for all external server response until it is resetted

Examples:

Call:

curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"

Result:

200:

Force response code: 500 set for all external server response until it is resetted

Reset response-manipulation¶

It is possible to reset the response manipulation on the external server

POST¶

Clears specific response code for all (the next) external server operation.

URL path:

/serveradmin/forceresponse?code=<http-response-code>

Parameters:

code: (Required)

The HTTP response code to return.

Responses:

200:

Force response code has been resetted for all external server responses

Examples:

Call:

curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"

Result:

200:

Force response code has been resetted for all external server responses

Response time manipulation¶

It is possible to set a period of time to delay response time.

POST¶

Force delayed response of all A1 responses. The setting will remain until the delay is set to ‘0’

URL path:

/serveradmin/forcedelay?delay=<delay-time-seconds>

Parameters:

delay: (Required)

The time in seconds to delay all responses.

Responses:

200:

Force delay: <expected_delay> sec set for all external server responses until it is resetted

Examples:

Call:

curl -X POST "http://localhost:9095/serveradmin/forcedelay?delay=5"

Result:

200:

Force delay: 5 sec set for all external server responses until it is resetted

Reset response time manipulation¶

It is also possible to reset delay response time.

POST¶

The setting will clear the delay.

URL path:

/serveradmin/forcedelay

Parameters:

None.

The time in seconds to delay all responses.

Responses:

200:

Force delay has been resetted for all external server responses

Examples:

Call:

curl -X POST "http://localhost:9095/serveradmin/forcedelay"

Result:

200:

Force delay has been resetted for all external server responses

Kafka Message Dispatcher¶

API Documentation¶

The O-RAN SC Kafka Message Dispatcher is a specific implementation of an A1 Simulator ref:calloutserver, which further redirects A1 Policy operations to a Kafka message topic, to be consumed by an external function.

A1 Policy are redirected as Kafka messages to a configured Kafka Topic to an external receiver, then responses from the external receiver are collected from another configured Kafka Topic. This provides a Kafka-based request-response abstraction for adding supplemental simulator behavior for particular A1 Policy Types. After a request message is sent, a response message will be expected within some configurable timeout interval (default: 30 sec). The topics to be used for particular A1 Policy Types is configured using a JSON map (Example: policytype_to_topicmap.json <../near-rt-ric-simulator/test/KAFKA_DISPATCHER/resources/policytype_to_topicmap.json>

Note: As with other A1 Simulator call-out servers, the Kafka message dispatcher functionality is only available for ‘STD_2.0.0’ version simulators.

The Kafka message dispatcher exposes a ‘Kafka Message Dispatcher’ REST API. This internal API is invoked directly by the A1 Simulator, and is not intended to be used by any other client. This API is documented in Kafka Message Dispatcher API and in OpenAPI YAML format:

API name
Kafka Message Dispatcher API	`link`

The Kafka message dispatcher also exposes an ‘Admin API’ to manipulate the behavior of the Kafka message dispather itself. The ‘Kafka Message Dispatcher Admin API’ is documented below:

Admin Functions¶

Health Check¶

GET¶

Returns the status of the Kafka Message Dispatcher.

URL path:

/

Parameters:

None.

Responses:

200:: OK

Examples:

Call:

curl -X GET "http://localhost:7075/"

Result:

200:

OK

Response manipulation¶

It is possible to manipulate the response of all operations on the Kafka Message Dispatcher module

POST¶

Force a specific response code for the all (the next) Kafka Message Dispatcher module operations. Unless it is reset, it will always respond the same response code back.

URL path:

/dispatcheradmin/forceresponse?code=<http-response-code>

Parameters:

code: (Required)

The HTTP response code to return.

Responses:

200:

Force response code: <expected code> set for all all dispatcher response until it is resetted

Examples:

Call:

curl -X POST "http://localhost:7075/dispatcheradmin/forceresponse?code=500"

Result:

200:

Force response code: 500 set for all dispatcher response until it is resetted

Reset response-manipulation¶

It is possible to reset the response manipulation on the Kafka Message Dispatcher module

POST¶

Clears specific response code for all (the next) Kafka Message Dispatcher module operation.

URL path:

/dispatcheradmin/forceresponse

Parameters:

code: (Required)

The HTTP response code to return.

Responses:

200:

Force response code has been resetted for dispatcher responses

Examples:

Call:

curl -X POST "http://localhost:7075/dispatcheradmin/forceresponse"

Result:

200:

Force response code has been resetted for dispatcher responses

Response time manipulation¶

It is possible to set a period of time to delay response time.

POST¶

Force delayed response of all dispatcher responses. The setting will remain until the delay is cleared.

URL path:

/dispatcheradmin/forcedelay?delay=<delay-time-seconds>

Parameters:

delay: (Required)

The time in seconds to delay all responses.

Responses:

200:

Force delay: <expected_delay> sec set for all dispatcher responses until it is resetted

Examples:

Call:

curl -X POST "http://localhost:7075/dispatcheradmin/forcedelay?delay=5"

Result:

200:

Force delay: 5 sec set for all dispatcher responses until it is resetted

Reset response time manipulation¶

It is also possible to reset delay response time.

POST¶

The setting will clear the delay.

URL path:

/dispatcheradmin/forcedelay

Parameters:

None.

The time in seconds to delay all responses.

Responses:

200:

Force delay has been resetted for all dispatcher responses

Examples:

Call:

curl -X POST "http://localhost:7075/dispatcheradmin/forcedelay"

Result:

200:

Force delay has been resetted for all dispatcher responses

Release-Notes¶

This document provides the release notes for the release of the A1 Simulator (previously called Near-RT RIC A1 Interface).

Version history A1 Simulator (previously called Near-RT RIC A1 Interface)
Release Data

Version history A1 Simulator (previously called Near-RT RIC A1 Interface)¶

Date	Ver.	Author	Comment
2020-06-12	2.0.0	Henrik Andersson	Bronze Release
2020-12-03	2.1.0	Henrik Andersson	Cherry Release
2021-12-15	2.2.0	Henrik Andersson	E Release
2022-06-29	2.3.0	Henrik Andersson	F Release
2022-08-24	2.3.1	Halil Cakal	F Maintenance Release
2022-12-15	2.4.0	Henrik Andersson	G Release

Release Data ¶

Bronze ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/64fb09fb50689f15c41ba61881d8119ea4d3c8b4
Release designation	Bronze
Release date	2020-06-12
Purpose of the delivery	Dockerized Near-RT RIC A1 simulator that supports multiple versions of the A1 interface.

Cherry ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/b77c6d13837acd857514cd3640dd0ca729fde1e1
Release designation	Cherry
Release date	2020-12-03
Purpose of the delivery	Add support for ORAN Spec A1-P v2 and introduce Enrichment simulator.

E Release ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/8b22a54a3ec8fd54e88b47c8a91c656ab844a4b3
Release designation	E
Release date	2021-12-15
Purpose of the delivery	Minor updates

F Release ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/595506e290356d26b8eebfab32ef8d3f625cbb0a
Release designation	F
Release date	2022-06-29
Purpose of the delivery	Added Callout hooks towards external server for create and delete operations

F Maintenance Release ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/514637b303ec7dc6390007be1a046189f7a9d169
Release designation	F Maintenance
Release date	2022-08-24
Purpose of the delivery	Added supplemental simulator behavior interface - kafka for south bound modules

G Release ¶

Project	Non-RT RIC
Repo/commit-ID	a1-interface/7d52964eaddd7052a4a111d4cda468fbb4dad7c5
Release designation	G
Release date	2022-12-15
Purpose of the delivery	Minor improvements