Skip to content

1. The xApp Documentation README.md

1.1 The README.md file

The README.md is a text file used to provide a reliable way to explain, describe and illustrate an xApp. Its content is fully text-based and allows special syntax using Markdown. The Markdown language is a lightweight markup language that allows the creation of formatted text using only a plain-text editor. It allows one to control the display of the document; formatting words as bold or italic, adding images, creating lists and much more. By filling the README.md file with xApp information, the Accelleran dRAX RIC will display its content automatically in the dRAX dashboard of the specific xApp. Thus, a full description of the xApp and its context can be provided with a special style for the illustration. An example README.md file is provided in the example folder of the xApp Framework.

Here are some links describing the Markdown features:

1.2 What we expect inside the README.md file

The README.md file is used to explain, describe and illustrate xApp behavior. It is the place where the xApp developer can give information about the xApp and its context.

The xApp README file generally contains the following elements:

  • A description of the xApp and its functionality
  • If the xApp is sharing data on the dRAX RIC Databus or not
  • If the xApp is sharing data, what is the format of the data
  • If the xApp is sharing data, which topic on the dRAX RIC Databus is the data shared on
  • If the xApp has additional custom API endpoints, and an explanation of what they are and what they do

Then, it is the responsibility of the xApp developer to feed the information correctly and give the best description possible for its xApp. The Markdown style formatting is also available to help xApps developers to structure the document but it’s not mandatory.

1.3 How the README.md is made available via /readme endpoint

As with the /config and /metadata endpoint on the xApp API, (consequently used for configuration purposes), the /readme endpoint retrieves the README.md file from the xApp Core and makes it available for other modules. Only the GET method is accepted for this endpoint.

To suit this behavior, the README.md must be a text file co-located with the xApp core files. An example of the README.md file is already provided in the xApp Framework Package to demonstrate the /readme endpoint functionality.

Thus, the README.md content is available the xApp API port:

http://<kubernetes_ip>:<xapp_api_port>/readme

Substitute <kubernetes_ip> with the advertised address of your Kubernetes cluster and the <xapp_api_port> by the exposed port of your xApp API.