XOS provides two programmatic interfaces: a RESTful API and TOSCA-based API. Earlier versions of XOS also includes xoslib, but it has since been deprecated.
Source for the XOS REST API lives in directory
xos/api. An importer
import_methods.py, auto-generates the REST API by searching
this directory (and sub-directories) for valid API methods. These
methods are descendents of the Django View class. This should include
django_rest_framework based Views and Viewsets.
We establish a convention for locating API methods within the XOS
hierarchy. The root of the api is automatically
/api/. Under that
are the following paths:
/api/service… API endpoints that are service-wide
/api/tenant… API endpoints that are relative to a tenant within a service
/api/tenant/cord/subscriber/ contains the Subscriber
API for the CORD service.
The API importer automatically constructs REST paths based on
where files are placed within the directory hierarchy. For example,
the files in
xos/api/tenant/cord/ will automatically appear at the
http://server_name/api/tenant/cord/. The directory
examples contains examples that demonstrate using the API from the
Linux command line.
Documentation for the REST API is available at docs.xos.apiary.io
Since Apiary requires documentation to be in a single file, XOS
provides a tool to combine small documentation files into one file, to
use it navigate to
xos/tests/api and run the command
node js). This command watches all
.md files in the
xos/tests/api/source/ directory, and upon detecting a change,
combines them in a single
dredd parses the
apiary.apib file, and performs requests against
all documented endpoints. It then compares the results against the
documented return values.
Once a new endpoint is added to the documentation, it is automatically
tested. If your service requires new model instances, relations,
or any other kind of data, you should add them in the
xos/tests/api/hooks.py file. You have the option to create this data
before_each hooks, or you can define a custom hook for your
endpoint, to do this check the
@hooks.before("Example > Example
Services Collection > List all Example Services") hooks and the
To run API tests, use the test-standalone configuration.
The REST API may be used via a number of programming languages. Below are a few examples using common tools and languages:
XOS supports use of TOSCA as a mechanism to configure and provision XOS services. There are two ways to use TOSCA in XOS.
The first is by loading and running a TOSCA program via the XOS GUI. This is done as follows:
The second is by running a TOSCA program using command line tools. To do this from inside the XOS container, you don’t have to add the specification to the data model, and you don’t have to wait for XOS to queue and execute the specification. The command-line tool returns output on completion. To execute a TOSCA specification, use the following command:
For a reference guide to XOS-specific TOSCA extensions, see http://guide.xosproject.org/tosca_reference.html
For samples of XOS TOSCA specifications, consult the xos/tosca/samples section of the XOS git repository.