1. xApp REST API¶

The dRAX RIC platform has been, in its own roots, designed to use an adaptable approach. Through its genuinely defined architecture, an xApp can be developed and extended depending on needs to provide infinite tastes and flavors to the RIC.

The xApp Library, therefore, also includes Tornado as the API framework. Accelleran has already pre-built a number of xApp API endpoints that are used for xApp Configuration purposes. On the other hand, the developer can also take advantage of the xApp Library abstractions to create their own custom API endpoints. This allows xApp developers to create handlers for the API endpoint requests (POST, GET, DELETE, PUT, etc.), to create different actions per endpoint depending on the requests received and add support for event-based actions. For more information about the tornado framework, you can reach the following link:

https://www.tornadoweb.org/en/stable/

1.1 Overview¶

The xApp API has a couple of endpoints predefined:

These prebuilt API endpoints are used to:

1. To enable the dRAX RIC to discover the xApp and make it visible through the dRAX Dashboard
2. To enable the real-time configuration of the xApp
3. To enable the developer to expose functionalities of the xApp to the rest of the dRAX as well as to external systems
4. To easily fetch the documentation and metadata of the xApp

The /api is the extendable and optional endpoint that we have left up to developers to implement the functionalities. Example code for handling the /api endpoint can be found in the xApp Framework example/core/restapi.py. This way we keep the xApp Core the single point of focus for the developers. The use of /api is simply convention and developers can rename it as they wish. We will, however, use it here in this document when referring to developer created custom API endpoints.

1.2 Adding an endpoint behind the /api¶

To create a new entry point for your xApp under /api, the xApp developer simply needs to add a handler to the xApp builder .restapi() call.

For each endpoint defined in the list, a callback class is associated. These classes will be called each time the endpoint is triggered and can also be overloaded at needs to handle every REST request (GET, PUT, POST, DELETE, ...).

In the following example /api/, /api/actions and /api/request have been defined as endpoints with corresponding handlers.

builder.restapi([
      ("/api/", MainApiHandler),
      ("/api/actions", ActionsHandler),
      ("/api/request", RequestHandler),
  ])

Then, the endpoint handler can be declared to ensure defined behaviors per REST request.

In the following example, the RequestHandler class is defined for the /api/request endpoint. It handles:

• A first initialize function used to save a weak reference to the xapp class
• A get function that handles the REST request GET for this specific endpoint
• A post function that handles the REST request POST for this specific endpoint.

class RequestHandler(tornado.web.RequestHandler):
    def initialize(self, xapp):
        self.xapp = xapp
        self.write("init request handler\n")
    def get(self):
        self.write("request handler get\n")
    def post(self):
        self.set_header("Content-Type", "text/plain")
        self.write("You wrote " + self.get_body_argument("message"))

Hence, every endpoint is bound to a specific class handler that will define and organize all the expected management and behaviors when it will be triggered.

1.3 How to extend the context of the newly added API endpoint¶

While deploying a new endpoint, xApp developers also might want to extend its functionalities to have the hand on much wider components. To have access to the functionalities of these components, a reference to the xapp will need to be provided to the handlers.

This reference will be forwarded automatically to the user class initialization function for further use inside it. In addition metaclassing can be used to pass additional parameters to the handler.

It allows xApps developers to declare a dictionary of variables and information that will be made automatically available in the initialize function of the handler definition.

The following example introduce the notion of context inside the callback class with the listener object passed to the MainApiHandler:

def create_handle(listener):
    class MainApiHandler(tornado.web.RequestHandler):
        def initialize(self, xapp):
            self.xapp = xapp
        def get(self):
            self.write("Write a message into the listener...\n")
            listener.send_data("topic", "Message from restapi main handler")
            self.write("Message written.\n")
    return MainApiHandler

builder.restapi(["/api", create_handle(my_listener)])

In this example listener is an object of a user-defined class meant to forward logic to a main thread.

This way a certain message from the API can be forwarded to the main application. Hence, xApp developers can extend the possibilities of the xApps at needs in a fully configurable environment.

1.4 Reaching API endpoints¶

All the endpoints of the xApp can be reached using the following syntax:

http://<kubernetes_ip>:<xapp_api_port>/<endpoint>

Just substitute with the advertised address of your Kubernetes cluster and the by the exposed port of your xApp API. This can be found on the dRAX Dashboard by clicking the Show button under services, and locating the xapp-api service information. Finally, change the <endpoint> to whichever endpoint you need (/config, /metadata/ /api/custom_endpoint, etc.).