Contents

1   Introduction

This document describes the Device Management Representational State Transfer (REST) API. The API offers the possibility to:

• Add, remove, update, and get devices in the Device Repository.
• Management of device information like login credentials, device type and the use of Resource Configuration features like Candidate Store and Configuration Validation.
• Trigger Device Discovery and Reconciliation.

For more information about the Device Repository and device related functionality, refer to Function Specification Resource Configuration, Reference [1] and User Guide for Resource Configuration, Reference [2].

1.1   Purpose and Scope

All functionality exposed over the REST API for Device Management is also available in the Resource Configuration GUI. For smaller solutions of Resource Configuration it is convenient to add and remove devices manually in the system, using this GUI. When the number of devices is increasing, it is recommended to automate the introduction of new devices in the solution. The REST API described in this document is then needed to manage the devices in Resource Configuration from another system.

1.2   Target Group

The target group for this document is as follows:

• System Integrator

For more information about the different target groups, see Library Overview, Reference [3].

1.3   Typographic Conventions

Typographic conventions are described in Library Overview3, Reference [3].

1.4   Prerequisites

To use this document fully, users must meet the following prerequisites:

• Basic knowledge about the Dynamic Activation product
• Knowledge about REST.
• Knowledge about json.

For information about Resource Configuration in Ericsson Dynamic Activation (EDA), refer to Function Specification Resource Configuration, Reference [1].

1.5   Operations

The following HTTP request methods are used:

• GET

  The GET method requests a representation of the specified resource. Requests using GET only retrieves data and have no other effect.

• POST

  The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI, or an item to add to a database.

• PUT

  The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified.

• DELETE

  The DELETE method deletes the specified resource.

See the following table for all available URLs and corresponding operations.

All requests and responses use the Content-Type application/json.

1.6   Web Service Interface

Resource Configuration provides Web Application Description Language (WADL) file to use as a base when creating REST interface.

The interface.zip file containing the WADL file can be found in /home/dveinstaller/da/. It is also possible to download the zip file and store it in an appropriate area by following below instruction:

1. Save the zip file, Dynamic_Activation_WSDL_ and_ XSD_ files.zip, to a local folder.
2. Unpack the zip file.
3. Go to \EDAinterface\webservice_provisioning_rest\wadl\Applications\Resource_Configuration.

2   Authentication

All the requests in this document must include the HTTP Basic authentication header to provide username and password. The basic authentication string uses Base64 encoding.

2.1   Example

This section contains a complete example of an authorization header that can be reused in all operations mentioned later in this document.

GET /scm-rest/device-repository/devices/device1/ HTTP/1.1
Host: 10.0.0.2:8383
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/json

3   Device Management Data

This chapter describes the data attributes related to the device. For more information about each operation, see Section 4.

4   Device Management Operations

4.1   /scm-rest/device-repository/admin-states

4.1.1   GET

This operation fetches all valid admin states.

Parameters:

N/A

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/admin-states

Response body example:

[
  "IDLE",
  "INSTALLED",
  "UNKNOWN",
  "NOT INSTALLED",
  "INACTIVE",
  "ACTIVE"
]

4.2   /scm-rest/device-repository/device-categories

4.2.1   GET

This method gets all valid device categories.

Parameters:

This operation contains no parameters.

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/device-categories

Response body example:

[
    "OTHER",
    "CE",
    "Proxy",
    "Jump Server",
    "PE",
    "FIREWALL"
]

4.2.2   POST

This method adds new device category.

Parameters:

N/A

Request example:

The request body {"category":"MY_CATEGORY"} is sent to the URL https://10.0.0.2:8383/scm-rest/device-repository/device-categories.

Response body example:

{"category":"MY_CATEGORY"}

4.3   /scm-rest/device-repository/devices

This operation consists of the methods described below.

4.3.1   GET

Get a page of devices by filtering criteria.

Parameters:

The following parameters can be used when filtering:

Request body:

N/A

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices?pageIndex=1&pageSize=50&adminStates[]=ACTIVE&categories[]=CE&types[]=Junos_Template_CLI&protocols[]=SSH_CLI&modes[]=CANDIDATE+STORE&searchPattern=device

Response body example:

{
    "totalNrOfPages": 1,
    "currentPage": 1,
    "listItems": [
        {
            "masterIdentifier": "device1",
            "identifiers": [],
            "adminState": "ACTIVE",
            "modes": [
                "CANDIDATE STORE",
                "CONFIGURATION VALIDATION"
            ],
            "subModes": [
                "UPDATE REPOSITORY"
            ],
            "types": [
                "Junos_Template_CLI"
            ],
            "accessPoints": [
                {
                    "protocol": "SSH_CLI",
                    "address": "10.0.0.3",
                    "parameters": {
                        "parameterKey1": "parameterValue1"
                    },
                    "credentials": {
                        "username": "admin",
                        "password": "admin"
                    }
                }
            ],
            "info": {
                "RECONCILIATION": "FAILED"
                "RECONCILIATION_ERROR": "Unexpected error - detailed message found here"
            },
            "description": "This is the description of the device",
            "candidateConfigCount": 0,
            "category": "CE"
        }
    ]
}

4.3.2   POST

This method adds a new device to the system.

Parameters:

N/A

Request body example:

{
    "masterIdentifier": "device1",
    "adminState": "ACTIVE",
    "types": ["Junos_Template_CLI"],
        "parameters": {"parameterKey1": "parameterValue1"},
    "category": "CE",
    "modes": [
      "CANDIDATE STORE",
      "CONFIGURATION VALIDATION"
    ],
        "subModes": ["UPDATE REPOSITORY"],
    "description": "This is the description of the device",
    "accessPoints": [
        {
            "credentials": {
                "username": "admin",
                "password": "admin"
            },
            "parameters": {},
            "address": "10.0.0.3:8000",
            "protocol": "SSH_CLI"
        }
    ]
}

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices

Response body example:

{

    "identifiers": [],
    "modes": [
        "CANDIDATE STORE",
        "CONFIGURATION VALIDATION"
    ],
    "subModes": [
        "UPDATE REPOSITORY"
    ],
    "types": [
        "Junos_Template_CLI"
    ],
    "parameters": {
        "parameterKey1": "parameterValue1"
    },
    "accessPoints": [
        {
            "parameters": {},
            "credentials": {
                "password": "admin",
                "username": "admin"
            },
            "protocolParameters": {},
            "protocol": "SSH_CLI",
            "address": "10.0.0.3:8000"
        }
    ],
    "info": {},
    "masterIdentifier": "device1",
    "adminState": "ACTIVE",
    "description": "This is the description of the device",
    "candidateConfigCount": null,
    "category": "CE"
}

4.4   /scm-rest/device-repository/devices/{identifier}

This operation consists of the methods described below.

4.4.1   GET

This method gets the specific device by specifying deviceId.

Parameters:

This operation contains a path parameter which sends the request as a string Identifier.

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices/device1

Response body example:

{
    "identifiers": [],
    "modes": [
        "CANDIDATE STORE",
        "CONFIGURATION VALIDATION"
    ],
    "subModes": [
        "UPDATE REPOSITORY"
    ],
    "types": [
        "Junos_Template_CLI", "IOS_Template"
    ],
    "parameters": {"parameterKey1": "parameterValue1"},
    "accessPoints": [
        {
            "parameters": {
                "parameterKey1": "parameterValue1"
            },
            "credentials": {
                "password": "admin",
                "username": "admin"
            },
            "protocolParameters": {},
            "protocol": "SSH_CLI",
            "address": "10.0.0.3:8000"
        }
    ],
    "info": {
            "RECONCILIATION": "FINISHED"
        },
    "masterIdentifier": "device1",
    "adminState": "ACTIVE",
    "description": "This is the description of the device",
    "candidateConfigCount": null,
    "category": "CE"
}

For a more detailed description of the different parameters, see Section 3.

4.4.2   PUT

This method updates information about a specific device with deviceId.

Parameters:

This operation contains a path parameter which sends the request as a string Identifier.

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices/device1

Request body example:

 {
    "identifiers": [],
    "adminState": "ACTIVE",
    "types": [
        "Junos_Template_CLI",
        "IOS_Template"
    ],
    "category": "CE",
    "modes": ["CONFIGURATION VALIDATION"],
    "subModes": ["UPDATE REPOSITORY"],
    "description": "This is the description of the device",
    "parameters": {"parameterKey1": "parameterValue1"},
    "accessPoints": [
        {
            "protocol": "SSH_CLI",
            "address": "10.0.0.3",
            "parameters": {},
            "credentials": {
                "username": "admin",
                "password": "admin"
            }
        }
    ]
}

Response body:

N/A

4.4.3   DELETE

This method removes a specific device.

Parameters:

This operation contains a path parameter which sends the request as a string Identifier.

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices/device1

Response body:

N/A

4.5   /scm-rest/device-repository/devices/{identifier}/config-sync

This operation consists of the methods described below.

4.5.1   POST

This method triggers a device reconciliation to align the Device Repository with the provisioned devices.

Parameters:

This following parameters can be used when reconciling a device.

Request example:

https://10.0.0.2:8383/scm-rest/device-repository/devices/device1/config-sync

Request body example:

 {
    "syncType": "UPDATE DEVICE",
    "cached": "false"
}

Response body

N/A

5   Faults or Errors

A REST error message consists of an error code and a message describing the error.

The following table covers Device Management REST error codes. They can appear in any REST response.

The following is an example of a REST error message:

{
    "errorCode": 404,
    "description": "Not found."
}

Reference List