Anuta ATOM

ATOM API Guide

Table of Contents

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.

Intended Audience

This document is meant to be used by the system integrators, IT administrators, and developers who want to develop client applications using ATOM.

Support

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.

1

Understanding ATOM APIs

Introduction

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 Architecture

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.

4

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.

  • Customized Operations

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

API Entities

The API model includes these programmatic entities:

  • API Objects

  • API Methods

API Objects

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.

Schema Path

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

Example

/controller:credentials/credential-sets/credential-set

Instance path

The relative path identifies an object from its siblings within the context of its parent object.

Example

/controller:credentials/credential-sets/credential-set=XYZ

where XYZ is the name of a Credential Set

Object Representations

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.

Format

Content-Type header

Accept header

Extension

JSON

application/json

application/json,

application/yang-data+json

.json

XML

application/xml

application/xml,

application/yang-data+xml

.xml

API Methods

ATOM supports the standard RESTCONF methods ‐ PUT, PATCH, GET, POST, and DELETE. The base URL RESTCONF based operations is https://<server‐ip>/restconf

HTTP Method

Operation Type

Description

GET

Retrieve

Retrieves or lists the representation of an existing object

POST

Create

Create an object

PUT

Update

Modifies the existing object

PATCH

Update

Applies the delta instead of replacing the entire object

NOTE: ATOM supports only the plain “PATCH”method

DELETE

Delete

Deletes an existing object

URL Encodings

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

Response codes

HTTP Status Codes returned to the client in response to the request sent to the ATOM server.

Status Code

Status Description

200 OK

Successful

201 Created

The request is valid. The requested object was created.

202 Accepted

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.

401 Unauthorized

An authorization header was expected but not found.

403 Forbidden

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

405

Method Not Allowed

The HTTP method specified in the request is not supported for this object.

406

Not Acceptable

The requested resource is only capable of generating content which is not acceptable according to the Accept Headers sent in the request.

409 Conflict

The requested object or resource is in conflict.

415

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

Authentication

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.

Example:

curl -L -k -X POST ‘<ATOM_URL>/auth/realms/system/protocol/openid-connect/token’ -H ‘Content-Type: application/x-www-form-urlencoded’

–data-urlencode ‘grant_type=password’

–data-urlencode ‘scope=openid’

–data-urlencode ‘client_id=<CLIENT_ID>’

–data-urlencode ‘client_secret=<CLIENT_SECRET>’

–data-urlencode ‘username=<USERNAME>’

–data-urlencode ‘password=<PASSWORD’

Output:

{“access_token”:”eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJFY3RabXFUMjZwYlU5dDdHcHh3ZWp6YV9KaENhV1V3S3hJRS1JSzVKX0RnIn0.eyJleHAiOjE2MTQzMDkyNjQsImlhdCI6MTYxNDMwNTY2NCwianRpIjoiMTA0MGI0N2UtMzMwNi00ODc0LTlkNGEtNGU0NTNmYTQ3N2YwIiwiaXNzIjoiaHR0cHM6Ly9hcHAuMTcyLjE2LjIyLjIwNy5uaXAuaW86MzI0NDMvYXV0aC9yZWFsbXMvc3lzdGVtIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6Ijk4NmU5MDMyLTI0Y2YtNDdhOS1hMWY5LTFjNzJiY2RjOGE5MiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFub3RoZXItY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6Ijk3MDlhZjVhLWI0ZTYtNDYwNy1hNjZjLWRmMWJmZDE4NzcxYyIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiZ2l2ZW5fbmFtZSI6IiIsImZhbWlseV9uYW1lIjoiIiwiZW1haWwiOiJhZG1pbkBhdG9tLmxvY2FsIn0.Y6Y7HaF5-Wqr7MlK_Dh9MqZuWTMPjTJ7JNOGGc7teIJm0e2I3JXokXURbZlCpolEYjdGV2Pw12l0Lj-G1l03_A–PhdzPRinrEf0wbX3JHk8DpIoe9vKykxTMi-PmEDkYzCIuGLTBx7GTombuft8sJ2VJejs-uoTshWd6lAW289efRQXmn_bFQhAuM_dDKHxGBOZReapf6FhMo3qDSg2Rg4mvn7_R7X7rYMy0ko0tFn4hNCsEx-U1cbA1roH-b3GAKe_IsNtW6aneaMqegrYpNYluYvMkuY_MDXz8eX9GHSYKg50mdeVbgh3_EFHhXQ3hDQMRej3ataWIC0zC4u6AQ”,”expires_in”:3600,”refresh_expires_in”:1800,”refresh_token”:”eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzhkNTc1YS0zYTg3LTQ5Y2YtYTcwOS0xOGFlYjcxZGViYmIifQ.eyJleHAiOjE2MTQzMDc0NjQsImlhdCI6MTYxNDMwNTY2NCwianRpIjoiMDVjYTVmMjItNThkZi00NzUwLWE2MGMtZDBmNDdmZDAyMmNiIiwiaXNzIjoiaHR0cHM6Ly9hcHAuMTcyLjE2LjIyLjIwNy5uaXAuaW86MzI0NDMvYXV0aC9yZWFsbXMvc3lzdGVtIiwiYXVkIjoiaHR0cHM6Ly9hcHAuMTcyLjE2LjIyLjIwNy5uaXAuaW86MzI0NDMvYXV0aC9yZWFsbXMvc3lzdGVtIiwic3ViIjoiOTg2ZTkwMzItMjRjZi00N2E5LWExZjktMWM3MmJjZGM4YTkyIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFub3RoZXItY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6Ijk3MDlhZjVhLWI0ZTYtNDYwNy1hNjZjLWRmMWJmZDE4NzcxYyIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.XZ4QnaKY_SRKxQdmQTN72PLiTX-g_Ppwmk7FCi9Aegk”,”token_type”:”Bearer”,”id_token”:”eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJFY3RabXFUMjZwYlU5dDdHcHh3ZWp6YV9KaENhV1V3S3hJRS1JSzVKX0RnIn0.eyJleHAiOjE2MTQzMDkyNjQsImlhdCI6MTYxNDMwNTY2NCwiYXV0aF90aW1lIjowLCJqdGkiOiI0YjUyODgxMS01OTMzLTRiY2YtOGU3Yy03MWViYjc1MDQyYTEiLCJpc3MiOiJodHRwczovL2FwcC4xNzIuMTYuMjIuMjA3Lm5pcC5pbzozMjQ0My9hdXRoL3JlYWxtcy9zeXN0ZW0iLCJhdWQiOiJhbm90aGVyLWNsaWVudCIsInN1YiI6Ijk4NmU5MDMyLTI0Y2YtNDdhOS1hMWY5LTFjNzJiY2RjOGE5MiIsInR5cCI6IklEIiwiYXpwIjoiYW5vdGhlci1jbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiOTcwOWFmNWEtYjRlNi00NjA3LWE2NmMtZGYxYmZkMTg3NzFjIiwiYXRfaGFzaCI6IlJsV2Z1VVlCWWhsWXppc05IdTc3SmciLCJhY3IiOiIxIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiIsImdpdmVuX25hbWUiOiIiLCJmYW1pbHlfbmFtZSI6IiIsImVtYWlsIjoiYWRtaW5AYXRvbS5sb2NhbCJ9.GZ9eYBaCtGesAGGvhZPBiEQ85Vtf6Ae3dP1tEVUUbZBKK_Su_B49TYO1Zw9_96hR91YHp1_4xn-n1MEDrd54gHCtAmdZi4Woj9X9QUAWFLchQ0n2qVI0DdE4MXUTfnXopmVkGBxQSDSXoom8Fj9QiEBkmKM25xIFMDMGoXz75e3VXu8hHUDfCPFP2Tj5Y-oEC_s8pGbv7P7e5GLMpUG15F82_JE_VOUcGN2BbTDolwchHD53mNRaJ2MwTIpsfQGtZkghCyulCXXgh-k7AE2jkS-BQVXB392DwgKNyDxONxdAaxNOB-wqBtNwwfXwU9sQGCh6sgo6dPr8rwroPoxvVw“,”not-before-policy”:0,”session_state”:”9709af5a-b4e6-4607-a66c-df1bfd18771c”,”scope”:”openid profile email”}

Extract the id_token from the above output.

Example:

$ export ID_TOKEN=<ID_TOKEN>

$ curl -L -k -X GET ‘<ATOM_URL>/restconf/data/tenants.json’ -H “Authorization: Bearer $ID_TOKEN”

{“controller:tenants”:{“@”:{“shared-with”:”system.*”},”tenant”:[{“@”:{“shared-with”:”system.*”},”sub-tenancy-enabled”:false,”name”:”system”,”description”:”system tenant”,”dry-run”:false},{“@”:{“shared-with”:”system.*”},”sub-tenancy-enabled”:false,”name”:”acme”,”dry-run”:false},{“@”:{“shared-with”:”system.*”},”sub-tenancy-enabled”:false,”name”:”Coke”,”dry-run”:false},{“@”:{“shared-with”:”system.*”},”sub-tenancy-enabled”:false,”name”:”Pepsi”,”dry-run”:false}]}}

New Client

If a new client for API access is desired, follow these steps.

  • Login to the ATOM access manager using admin credentials at https://<ATOM_URL>/auth/ (e.g:https://app.10.10.7.30.nip.io:32443/auth)

  • 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:

  • Owner

  • shared-with

‘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:

system

Acme

North

South

Campus-1

Company-2

Company-3

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’

System

Acme

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

System

Tenant-1

Tenant-2

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.

#

Description

Client Request

Output

Notes

1

A transaction is started by invoking ‘begin‐task’ rpc

POST /restconf/operations/tasks:begin-task

<taskID>id</taskID>

Example

<taskID>6db7bfb2-930f-4257-98a7-7b01dd342e04</taskID>

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

Example

X-TASK-ID = 6db7bfb2-930f-4257-98a7-7b01dd342e04

2

Create a VRF

POST

/controller:devices/device=<device_id>

With header

X‐TASK‐ID = 6db7bfb2‐930f‐4257‐98a7‐7b01dd342e04

Payload:

<vrf> <name>pevrf</name>

<rd>100:1</rd>

</vrf>

Status:

HTTP/1.1

202 Accepted

<taskId>6db7bfb2-930f-4257-98a7-7b01dd342e04</taskId>

3

Any additional CRUD operations

Can be done using the same TASKId and the header.

4

Commit the transaction

POST

/restconf/operations/tasks:commit-task.xml

With Header

X‐TASK‐ID = 6db7bfb2‐930f‐4257‐98a7‐7b01dd342e04

Status: HTTP/1.1 202 Accepted

<taskId>6db7bfb2-930f-4257-98a7-7b01dd342e04</taskId>

5

Check the task details or wait for notification

POST

restconf/operations/tasks:get-basic-task-detail.xml

Payload:

<taskId>6db7bfb2-930f-4257-98a7-7b01dd342e04</taskId>

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.

Option

Type

Description

do-not-send-commands-to-devices

boolean

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

validation‐scope‐type

1. COMMITTED_DATA

2.UNCOMMITTED DATA

enum

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).

fail‐fast

boolean

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).

command-sequence-policy

enum

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:

Task States

% Completion

Task Status

Description

Yet to Begin

0%

NOT_STARTED

Execution not started

Running States

0% to 100%

IN_PROGRESS

VALIDATED

RESOURCES_RESERVED

RESOURCES _PROVISIONED

OPERATIONAL_RESOURCES_RESERVED

Resources allocated for service complete on ATOM

OPERATIONAL_RESOURCES_UNRESERVED

Service allocated resources are unreserved on ATOM

50%

SCHEDULED_FOR_PROVISION

Task is scheduled for provisioning

50%

WAITING

Task is waiting for approval to provision configuration

END STATES

SUCCESS

COMPLETE

Operation completed successfully

ERROR

RESERVE_RESOURCES_FAILED

RESERVE_OPERATIONAL_RESOURCES_FAILED

Resource allocation (config generation) for service is failed on ATOM

PROVISION_RESOURCES_FAILED

Execution of configuration of service on the device failed or device connection timeout

ERROR

Some of the error messages:

  • Transaction rolled back. Rollback completed.

  • Operation failed on agent:

  • Database exception

  • Internal exception

  • Operation failed due to device connectivity issues during service provisioning

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:

/restconf/data/controller:credentials/credential-sets?fields=credential-set(name;transport-type)

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:

/restconf/data/controller:credentials/credential-sets/credential-set=xyz?fields=name;port-number

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”:

/restconf/data/controller:devices.xml?fields=device/l3features:vrfs/vrf(name;rd)

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:

/restconf/data/controller:devices/device=172.16.1.130.xml?depth=2

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:

/restconf/data/controller:credentials/credential-sets.xml?limit=2

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:

  • Set 1

  • Set 2

  • Set 3

  • Set 4

Request: GET /restconf/data/controller:credentials/credential-sets.xml?limit=2&offset=1

Response:

Set 2

Set 3

Request: /restconf/data/controller:credentials/credential-sets.xml?limit=2&offset=2

Response:

Set 3

Set 4

Request: /restconf/data/controller:credentials/credential-sets.xml?offset=3

Response:

Set 4

Invoking ATOM APIs from REST Client

Introduction

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.

  • Click Send

  • The resulting Response pattern is displayed in the text box.20

Example

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.

Request

URI https://<VM-IP>/restconf/operations/tasks:begin-task.xml

where VM-IP is the IP address of the ATOM VM

Payload: Not Applicable

Operation: POST

Headers

APIVersion: 2.0

Content-Type: application/xml

Response

200 OK

<taskId>613f5f45-dd29-4783-8527-7303756db312</taskId>

  • Enter the value of the <taskId>, generated in the above step, in the X‐TASK‐ID field in the Headers tab.

  • Commit the transaction.

Request

URI https://<VM-IP>/restconf/operations/tasks:commit-task.xml

where VM IP is the IP address of the ATOM VM

Payload: Not Applicable

Operation: POST

Headers

APIVersion: 2.0

Content-Type: application/xml

X-TASK-ID: 613f5f45-dd29-4783-8527-7303756db312

Response

200 OK

<taskId>613f5f45-dd29-4783-8527-7303756db312</taskId>

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.

Request

URI https://<VM-IP>/restconf/operations/tasks:get-full-task-detail.xml

where VM IP is the IP address of the ATOM VM

Payload:<taskId>613f5f45-dd29-4783-8527-7303756db312</taskId>

Operation: POST

Headers

APIVersion: 2.0

Content-Type: application/xml

Response

200 OK

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

Request

URI https://<VM-IP>/restconf/data/controller:credentials/

credential-sets.xml?

where VM_IP is the IP address of the ATOM VM

Body:

<credential-set>

<enable-password>

elastic

</enable-password>

<snmp-version>

SNMPV2C

</snmp-version>

<cli-configcmd-time-out>

100

</cli-configcmd-time-out>

<time-out>

10

</time-out>

<username>

admin

</username>

<port-number>

23

</port-number>

<snmp-read-community-str>

public

</snmp-read-community-str>

<config-retrieval-credential>

true

</config-retrieval-credential>

<password>

Elastic+123

</password>

<transport-type>

TELNET

</transport-type>

<name>

restIOS

</name>

<cr-wait-time>

10

</cr-wait-time>

<command-execution-wait-time>

500

</command-execution-wait-time>

<number-of-retries>

10

</number-of-retries>

<cr-time-out>

5

</cr-time-out>

</credential-set>

Response

Status:202

Reason: Accepted

Onboarding a device to ATOM

Request

URI https://<VM-IP>/restconf/data/controller:devices.xml?

where VM_IP is the IP address of the ATOM VM

Body:

<device>

<name>

device139

</name>

<management-mode>

MANAGED

</management-mode>

<manage-by-management-station>

false

</manage-by-management-station>

<credential-set>

restIOS

</credential-set>

<id>

139device

</id>

<mgmt-ip-address>

172.16.1.139

</mgmt-ip-address>

</device>

Response

Status:202

Reason: Accepted

Creating a vrf entry on the device

Request

URI https://<VM-IP>/restconf/data/controller:devices/device=<device-id>/vrfs.xml?

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

Body:

<vrf>

<name>

vrf-internal

</name>

</vrf>

Response

Status:202

Reason: Accepted

Creating the Service

Request

URI https://<VM-IP>/restconf/data/controller:services.xml?

where VM_IP is the IP address of the ATOM VM

Body:

<l3service>

<name>test_sub_intf2</name>

<device-ip>172.16.1.139</device-ip>

<interface-mode>sub-interface</interface-mode>

<vrf>vrf2</vrf>

<vlan-id>1002</vlan-id>

<interface>FastEthernet8</interface>

<ip-address>192.168.15.1</ip-address>

<netmask>255.255.255.0</netmask>

</l3service>

Response

Status:202

Reason: Accepted

Tools for API Development and Testing

Schema Browser

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.

Swagger

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.

    • RESTCONF Data

Select this option to view the APIs of the configuration data of the end points modelled in YANG

    • RESTCONF RPC

Select this option to view all the APIs of the RPCs modelled in YANG

    • RESTCONF Services

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

  • YANG Notifications

  • 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

  • SSE

  • Kafka Topics

  • Web Sockets

  • RabbitMQ

Notification Type And Detail

Notification Type

Notes

YANG Notification

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)

Custom Implementation