About This Guide
ATOM is a Restconf and YANG server from a Northbound Integration point of view.
Configuring/Customizing ATOM is largely achieved by using Restconf APIs against ATOM platform Yang models, Service Models and device models.
Knowledge of YANG and Restconf are required to work with ATOM APIs.
ATOM implements (largely) the following versions
There are two ways customers can integrate with ATOM.
Using YANG and ATOM APIs
Using Python SDK for Services And Device models development against ATOM APIs.
This document presents a high level view of ATOM APIs. Each Subsystem of ATOM, such as, Services Development, Device Driver Development, Workflows, Monitoring/Telemetry etc come with their individual detailed documentation.
This document is meant to be used by the system integrators, IT administrators, and developers who want to develop client applications using ATOM.
If you are facing any issues while using the ATOM APIs, please send a mail at support @anutanetworks.com or raise a ticket on the Support site.
Understanding ATOM APIs
ATOM enables customers and partners to develop their own device, service and operational models for specific network service delivery needs. ATOM API implements a RESTful HTTP workflow, using HTTPS Requests to the server and retrieving the information they need from the server’s Responses. Any client application that can send HTTP Requests over a secure channel using SSL through the port number 443 is an appropriate tool for developing RESTful applications with the ATOM API. The RESTCONF protocol operates on a conceptual data store defined with the YANG data modeling language. The server lists each YANG module it supports using a structure based on the YANG module capability URI format.
The conceptual data store contents, data‐model‐specific operations, and notification events are identified by this set of YANG module resources. All RESTCONF content identified as either a data resource, operation resource, or event stream resource is defined in YANG.
ATOM’s model‐driven, layered, and abstraction approach helps in delivering vendor‐neutral, extensible, and maintainable services.
For developing new services or device plugins customers can use ATOM Python SDK. Below snippet shows API interactions happening at different levels.
ATOM Data Model
ATOM platform configuration is largely captured as YANG models. Tasks, Scheduling, Users, tenants, Services, Device models, Monitoring Infra, Actions, RBAC rules, Device Compliance Rules, Events, Notifications and so on are some of the concepts modelled with YANG 1.1.
With this arrangement coupled with Restconf as the public API it is relatively easy for customers to understand how to integrate with ATOM. The yang models can be downloaded from the server. ATOM UI also gives a schema browser and has Swagger integration to help navigate these models.
Device and Service Models
ATOM contains an abstract device model and numerous vendor devices are already mapped to this abstract model. More vendor device support can be added by supplying the relevant device package. A device package can be developed using ATOM Python SDK.
If the device supports YANG models (native or Openconfig) ATOM can use those models instead of its abstract model.
It is also possible to bypass the YANG model layer and use the device native cli or REST API directly.
In addition to the device models, popular services such as L2VPN, L3VPN, Routing, ACLs etc. are available out‐of‐the‐box.
Using ATOM Data Model, the administrator can define highly customized operations that will be executed on a multi‐vendor install base. Any network configuration task can be defined as an operation. Operations can be executed via API or UI with ease.
Transaction support with commit/rollback
ATOM supports transactional operations both on the model itself as well as the devices.
ATOM supports a candidate configuration concept using which customers can stage their datastore(device configuration) changes until ready to commit. Upon commit, the staged changes will be merged to the running configuration datastore and devices are configured.6
The API model includes these programmatic entities:
API objects represent the ATOM entities that are modelled in YANG. Programmatic access is determined by the user permissions and access settings (which are configured by your organization’s system administrator). Most of the objects accessible through the API are read‐write objects. However, there are a few objects that are read‐only. To access the API objects, download the latest SDK containing all the objects and models expressed in YANG.
The schema path leads you to identify a specific target in the Data Model tree and contains the following attributes:
A parent object
Relative name that uniquely identifies the object among its siblings
Schema path name that uniquely identifies the object globally
The relative path identifies an object from its siblings within the context of its parent object.
where XYZ is the name of a Credential Set
Clients must be able to send Requests and receive Responses from the objects by using either the XML or JSON data serialization formats.
The format for both the Request and Response can be specified by adding an .xml or .json extension to the Request URI or Content‐Type header and the Accept header.
ATOM supports the standard RESTCONF methods ‐ PUT, PATCH, GET, POST, and DELETE. The base URL RESTCONF based operations is https://<server‐ip>/restconf
Retrieves or lists the representation of an existing object
Create an object
Modifies the existing object
Applies the delta instead of replacing the entire object
NOTE: ATOM supports only the plain “PATCH”method
Deletes an existing object
The target resource specified in a RESTCONF operation should adhere to the rules specified in the specification. For knowing the rules needed to encode a key value, refer RESTCONF documentation: https://tools.ietf.org/html/rfc8040#section-3.5.3
HTTP Status Codes returned to the client in response to the request sent to the ATOM server.
The request is valid. The requested object was created.
The request is valid and a task was created to handle it. Response contains the task object which can be used to monitor the task progress.
204 No Content
The request is valid and was completed. The response does not include a body.
400 Bad Request
The request body is malformed, incomplete, or otherwise Invalid.
An authorization header was expected but not found.
The requesting user does not have adequate privileges to access one or more objects specified in the request
404 Not Found
One or more objects specified in the request could not be found in the specified container
Method Not Allowed
The HTTP method specified in the request is not supported for this object.
The requested resource is only capable of generating content which is not acceptable according to the Accept Headers sent in the request.
The requested object or resource is in conflict.
Unsupported Media Type
The request entity has a media type which the server or resource does not support.
500 Internal Server Error
The request was received but could not be completed because of an internal error at the server
ATOM supports bearer token based authentication. You would need a client_id, client secret, username and password to obtain a token. Your administrator can provide the client_secret by logging to ATOM access manager at <ATOM_URL>/auth with admin credentials. Navigate to Clients -> atom -> Credentials and copy the Secret. If a new client for API access is preferred, follow the steps in New Client
Token is obtained by calling the REST API by setting client_secret obtained above, and your username and password and extract the id_token from the output.
curl -L -k -X POST ‘<ATOM_URL>/auth/realms/system/protocol/openid-connect/token’ -H ‘Content-Type: application/x-www-form-urlencoded’
Extract the id_token from the above output.
$ export ID_TOKEN=<ID_TOKEN>
$ curl -L -k -X GET ‘<ATOM_URL>/restconf/data/tenants.json’ -H “Authorization: Bearer $ID_TOKEN”
If a new client for API access is desired, follow these steps.
Navigate to Clients, export the client atom. It would download a file
Click on ‘Create’ on the same page (Clients) and import the previous downloaded file
Change the client name to appropriate name
Click Save, it should show the new Client page.
(Optional) Update ‘Valid Redirect URLs’ to the proper callback url.
Select ‘Credentials’ and note down the Secret, this is going to be client secret.
Edit the oauth2-proxy deployment file by ssh to master node
Execute kubectl edit deployment -n atom oauth2-proxy
Add https://<ATOM_URL>/auth/realms/system=<client_name> (e.g:https://app.10.10.7.30.nip.io:32443/auth/realms/system=newclient) under OAUTH2_PROXY_EXTRA_JWT_ISSUERS. If there are entries already, add the new one after a comma.
Multi Tenancy in ATOM
ATOM supports multi tenancy by attaching the tenant owning an object as part of the overall object key. There are 2 attributes attached to all objects:
‘system’ is always the root tenant.
Sub Tenancy is also supported.
The immediate child tenants of ‘system’ are called top level tenants.
Data of one top level tenant is completely isolated from another top level tenant.
Data of ‘system’ can be shared with top level tenants.
If tenants want to share data with ‘system’, it is possible too.
A sample hierarchy can be:
User guide has more details on Multi Tenancy Support in ATOM.
For the API interaction purposes, there is little change to the APIs to handle Multi Tenancy.
All APIs work the same when MT is enabled or not, for the most part. But, when sub tenants are involved and sharing of resources is required, sometimes, a client has to clarify which ‘owner’ of an object is being referenced. In those cases, the client program has to specify the ‘owner’ of objects as part of the payload to the APIs.
Multi Tenancy Specifics can be explained with the help of following examples:
When Multi Tenancy is disabled
This is the case when a client deploys ATOM on-premise.
In this deployment client assumes ‘system’ as self.
All the data is owned by ‘system’ [which is ‘client’ itself].
In this case there is no difference between MT and non-MT flavors of the APIs.
The rest of this document mainly describes Non-MT APIs.
Single Tenant under ‘system’
This scenario can happen in two cases.
In ATOM saas, when a deployment is dedicated to one client (Acme in the above example).
Or, when Acme deploys on-prem, enables Multi Tenancy and creates a top level tenant ‘Acme’.
In this scenario, there can be data sharing between system and Acme, mostly from system to Acme, to a lesser extent from Acme to system.
ATOM Deployment with Multiple Tenants but no Sub tenancy
This is the predominant style ATOM is deployed in SAAS.
But, a client can use this style in their on-prem too if they wish. Let us call this Customer SAAS, for lack of a better term.
We need to understand an important difference between ATOM SAAS and Customer SAAS.
‘Anuta’ is synonymous with ‘system’ in ATOM SAAS and
Customer is synonymous with ‘system’ in Customer SAAS.
Anuta employees are system users in SAAS and would not have access to tenants data (barring a few data categories). But, customer may be ok to let designated customer users see all the tenants data in their deployment.
ATOM Deployment with Multiple Tenants And Sub tenancy
In this scenario , due to sub tenancy and sharing, there is potential for duplicate data unless you clarify which tenant data is being referenced. Whenever this clarity is to be provided it reflects in the API payloads (that is where you specify which tenant data you mean to use).
Transactions Support in ATOM
ATOM RESTCONF implementation supports transactions on all the data mutations and remote procedure calls (rpcs, actions). All the device operations of one transaction are done as one logical atomic operation. Commit, rollback, and retry operations are supported.0
A sample transaction is illustrated below:
A transaction is initiated by calling the ‘begin-task‘ protocol operation which returns a taskID.
All subsequent calls carry a header ‘X‐TASK‐ID‘ with the above taskID.
When the client is ready to commit the transaction, it calls ‘commit-task‘ operation.
Progress of the task can be polled or notifications can be subscribed.
In case of any error, the commit can be retried by calling ‘commit-task’ again.
To rollback, the client calls ‘rollback-task’.
ATOM computes compensating commands for devices to which commands were sent in the transaction previously and applies the compensating commands to rollback. If any errors occur during the rollback, rollback can be retried calling ‘rollback-task’ again.
If the rollback is unsuccessful, manual intervention may be required.
Clients can monitor the Task detail to learn the progress of provisioning including any successful or failed device configuration attempts and commands.
A transaction is started by invoking ‘begin‐task’ rpc
This taskID should be used in all the subsequent operations that are required for this transaction.
All the subsequent calls should include a header.
X‐TASK‐ID = taskID
X-TASK-ID = 6db7bfb2-930f-4257-98a7-7b01dd342e04
Create a VRF
X‐TASK‐ID = 6db7bfb2‐930f‐4257‐98a7‐7b01dd342e04
Any additional CRUD operations
Can be done using the same TASKId and the header.
Commit the transaction
X‐TASK‐ID = 6db7bfb2‐930f‐4257‐98a7‐7b01dd342e04
Status: HTTP/1.1 202 Accepted
Check the task details or wait for notification
Setting the transaction control options
Default transaction behavior is specified by the global transaction policy parameter and they can be overridden by per transaction policy parameters. Following parameters are available for clients to control the transaction behavior.
Controls whether commands can be sent to the device.
true: Commit the data to ATOM datastore only, but no configuration changes will be applied on the device. Useful for testing or in the case of a brownfield environment to create services.
NOTE: This flag will be effective only if global dry‐run flag is set to false
Controls whether data validation scope is across transactions. This flag is similar to isolation control in traditional RDBS systems, but limited to just data validation. Allowed values are “COMMITTED_DATA” and “UNCOMMITTED_DATA”.
Validation will be done only using the committed data. Current transaction will not see changes done by other parallel transactions.
This is the default selection.
Data validation will be done using the uncommitted data. Current transaction will see changes done by other parallel transactions. This facility can be useful to assess the potential for transaction success/failure (for example during an approval process).
flag to control if reference validation to be done on each payload submission. false will defer the validation until the commit-task call. This lets the client submit payloads in an out of order (reference wise).
Controls whether the generated commands need to be ordered according to the dependencies specified in the model. Allowed values are DEPENDENCY_BASED and NONE
Understanding the Task States
Each operation (create, delete or update) on any entity managed by ATOM generates a task in ATOM.
A task can be in different states of progress and each state is described in the table below:
Yet to Begin
Execution not started
0% to 100%
Resources allocated for service complete on ATOM
Service allocated resources are unreserved on ATOM
Task is scheduled for provisioning
Task is waiting for approval to provision configuration
Operation completed successfully
Resource allocation (config generation) for service is failed on ATOM
Execution of configuration of service on the device failed or device connection timeout
Some of the error messages:
Handling Transaction Failures
If the transaction commit fails, the client can retry commit by invoking the ‘commit‐task’ operation again.
ATOM will apply only those commands that are not provisioned on the devices yet. If the client wishes to roll back the transaction, he can invoke ‘rollback‐task’ operation. ATOM undoes the provisioning done prior to the failure, thus restoring the device configuration to the original state. If the rollback also fails, the client retrieves the command set that needs to be applied on the device to restore the device configuration to its original state. The retrieved command set can manually be applied. Rollback can be retried by calling ‘rollback‐task’ operation again.
Using Query Parameters
Each RESTCONF operation allows zero or more query parameters to be present in the request URI. The specific parameters that are allowed depends on the resource type, and sometimes the specific target resource used, in the request.
Fields Query Parameter
The “fields” query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.
Example ‐ Retrieving all the entries of the target container
Let us assume that the target source is a Credential Set. To retrieve only the “name” and the “transport-type” fields of all the Credential Sets contained within ATOM, execute the following query:
Example ‐ Retrieving a specific entry of the container
Let us assume that the target source is a particular credential set of name “xyz”. To retrieve only the “name” and the “port number” fields of this credential set only, execute the following query:
Example ‐ Retrieving the child node of a node by providing path in the fields
Let us assume that the target source is “devices”. To retrieve the “name” and the “rd” fields of the “vrf” , a child node of the “device”:
Depth Query Parameter
The “depth” query parameter is an optional parameter which can be used to retrieve all the nodes under a resource till a specified hierarchy tree depth.
Example ‐ Retrieving all the entries of the target device for a specified depth
Let us assume that the target device is 172.16.1.130. Instead of retrieving complete tree under a device which can be of unknown depth, to retrieve only the interested childs available till a depth of 2 contained within ATOM, execute the following query:
Pagination in APIs
While sending an API request to ATOM, you can specify the number of resources, and the specify the record, starting from which the entries should be returned in the response body. The request header should contain the “limit” and the “offset” keywords in the URL.
Using the Limit parameter
The limit parameter tells the API how many records should be retrieved from the entire set of results:
Using the Offset parameter
The “offset” parameter tells the API where to start returning records from the entire set of results.
Let us assume that there are four Credential Sets available in the following order:
Request: GET /restconf/data/controller:credentials/credential-sets.xml?limit=2&offset=1
Invoking ATOM APIs from REST Client
You can access the ATOM RESTCONF APIs using either the GUI (REST Client) or CLI methods (cURL). Clients use HTTP methods such as GET, POST, PUT, and DELETE to make Requests to the ATOM server. The base URL to perform a RESTCONF based operation is https://<server‐ip>/restconf, where <server-ip> is the IP address of the ATOM VM
Any client application that can send HTTP Requests over a secure channel by using SSL can be an appropriate tool for developing RESTful applications with the ATOM API.
Constructing the API Request
A typical RESTCONF request is outlined below:
For this example, the web browser is Google Chrome and the REST client is POSTMAN and the chosen REST operation is GET.
Login to the VM using the administrator’s credentials
Open the POSTMAN rest client tool and follow the steps as outlined below:
In the Normal tab, go to the Enter request URL field, enter the URL in the following format.
Base URL : https://<server-IP>/restconf/data/controller.xml, where server-IP is the IP address of the ATOM server VM
Click the Authorization tab, choose Bearer Auth as the Authentication type.
Click the Headers tab to enter the following information:
Enter Content-Type and value as application/xml.
Select the appropriate operation (any of the RESTCONF operations) to be performed on the API object.
The resulting Response pattern is displayed in the text box.20
You can retrieve all the child entities in Credentials as illustrated below:
Open the POSTMAN client session in another browser.
In the Authorization tab, enter the token obtained as specified in the Authentication.
Click Send to send the request to the ATOM server.
Click the Body tab to see the Response obtained for the Request
Generating the X-TASK-ID
Before performing any RESTCONF operation such as POST, PUT or DELETE, a transaction ID should be generated. This transaction ID or the task ID is used to poll ATOM for all the subsequent tasks; commit_task and get-details-task. For all the RESTCONF operations, except GET, follow these steps:
Begin a transaction.
where VM-IP is the IP address of the ATOM VM
Payload: Not Applicable
Enter the value of the <taskId>, generated in the above step, in the X‐TASK‐ID field in the Headers tab.
Commit the transaction.
where VM IP is the IP address of the ATOM VM
Payload: Not Applicable
The task can be monitored by the following: https://<VM‐IP>/restconf/operations/tasks: get‐full‐task‐details.xml. Track task details by using above URL at that instance.
where VM IP is the IP address of the ATOM VM
Using the POST operation on the URL, you can periodically check progress until the task is completed.
Generating the Payload
From the “Schema Browser“, obtain the path of the entity which needs to be accessed. This will give the XML schema file of the YANG entity defined in ATOM.
Fill in the values for the fields described in the schema and send the request to ATOM as described in the section “Constructing the API Request “
Examples of ATOM APIs
This section contains different examples of restconf APIs for respective ATOM entity involved.25
Adding a Credential Set
where VM_IP is the IP address of the ATOM VM
Onboarding a device to ATOM
where VM_IP is the IP address of the ATOM VM
Creating a vrf entry on the device
where VM_IP is the IP address of the ATOM VM
where device-id is the unique ID with which device is onboarded to ATOM VM
Creating the Service
where VM_IP is the IP address of the ATOM VM
Tools for API Development and Testing
Schema Browser is a built-in tool of ATOM that provides a graphical view of the data model objects maintained in ATOM. You can query for the required object by providing the instance path of the target.
Login to ATOM and navigate to Administration > System > General Settings > Developer Options
Select the Enable Developer Mode option.
After selecting this option, navigate to Developers Tools > Schema Browser
In the search field, enter the path of the target to know the YANG schema of the object
For example, to retrieve the schema file of the Credential Set object as shown below:
Enter the path of the target in the Schema Path box.
Select the path from the drop‐down menu.
The schema file of the object defined in the data model is displayed in the below pane.
Looking into the schema representation, you can now construct the payload that can be sent in the Request body of an ATOM API. This can be sent as an input in the Request Body while constructing an API query.
You can now leverage the rich API set of ATOM using the Swagger UI integrated with ATOM.
Enable the Developer Mode in ATOM as follows:
Navigate to Administration > System > General Settings > Enable-Developer-Mode
Click RestConf APIs option by navigating to Developer Tools > RestConf APIs
In the newly opened browser tab of APIs Documentation, Select API drop-down, select the entity modelled in ATOM and you would like to explore the corresponding API request, response patterns.
Select this option to view the APIs of the configuration data of the end points modelled in YANG
Select this option to view all the APIs of the RPCs modelled in YANG
To view the APIs required to construct the service models in YANG
In the selected entity, look at the Request parameters that are required to construct the payload and substitute the values in these parameters by using the “Try it out” option available in the Swagger UI.
Notifications Support In ATOM
ATOM supports the following notification definitions
ATOM ChangeLog Notifications
Yang Notifications generated by Devices (when they support)
NAAS Events (Old generation style but still useful)
ATOM Infrastructure Monitoring Alerts
Device/Network Monitoring Alerts
Overall, the following transports are supported
Notification Type And Detail
These are the notifications defined in Yang modules and Sub modules, according to YANG 1.1 spec.
Notifications defined in ATOM yang modules will be implemented by ATOM.
If a user adds their own Yang schema with Notifications, the implementation details need to be supplied along with the Yang Schema. The way to supply the implementation is by defining an ‘ATOM Change Log’ script. See the next item.
ATOM CL Notification (ACLN)