The MSactivator™ provides a support for REST API. These API can be used by third-party service, application or script to manage your MSactivator™ instance.

Enabling REST API support

The API is enabled by default. No additional configuration is required.

Authentication

When making requests to MSactivator™ using the REST API, you will need:

  • A valid admin username and password (so that a token can be generated and an authenticated session can be established).

  • Appropriate access permissions for the requested resource (controlled by admin profile)

Using curl, you may save the authentication information as a HTTP header to allow subsequent requests to be accepted automatically.

authentication request
curl -H 'Content-Type: application/json' -XPOST -k https://<MSA IP or FQDN>/ubi-api-rest/auth/token -d '{"username":"username", "password":"user password"}'
authentication response
{
	"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJuY3Jvb3QiLCJpYXQiOjE2NTUxOTQ3MzMsImx2bCI6IjEiLCJleHAiOjE2NTUxOTgzMzN9.kVl5XuqbSnGI59k0dlHmhB9xmPsixS3X24yQ4oWD-S9GgcBWw7X-DAb_S5oqwd0h3R64i_Custn8GeFt34Yzow",  (1)
	"message": "authenticated",
	"authenticated": "true",
	"userDetails": {
		"id": 1,
		"baseRole": {
			"id": 1,
			"name": "Super Administrateur"
		},
		"externalReference": "NCLG1",
		"login": "ncroot",
		"operator": {
			"id": 1,
			"abonnes": [],
			"baseUrl": null,
			"isPartner": false,
			"name": "UBIqube",
			"prefix": "NCL",
			"address": {
				"city": "",
				"country": "",
				"fax": "",
				"mail": "",
				"phone": "",
				"streetName1": "",
				"streetName2": "",
				"streetName3": "",
				"zipCode": ""
			},
			"customersCount": 0,
			"adminsCount": 0,
			"managersCount": 0,
			"externalReference": ""
		},
		"acteurId": 1,
		"address": {
			"city": "",
			"country": "",
			"fax": null,
			"mail": "ncroot@msactivator.com",
			"phone": "",
			"streetName1": "",
			"streetName2": "",
			"streetName3": "",
			"zipCode": ""
		},
		"delegationProfileId": 0,
		"userType": 2,
		"delegations": null,
		"delegationsPerCustomer": {},
		"netceloId": {
			"ubiID": "NCLG1",
			"thePrefix": "NCL",
			"id": 1,
			"customerPrefix": "NCL"
		},
		"isExternalAuth": false,
		"activationKey": "",
		"ccla": false,
		"isActive": true,
		"passwordUpdateDate": "",
		"attachedCustomerIds": null,
		"firstname": "",
		"attachedOperatorIds": null,
		"manageAllUsers": true,
		"name": "ncroot",
		"sort": "NAME",
		"ldapAuthentication": false,
		"delegationProfilePerCustomer": {}
	}
}
1 auth TOKEN

Use the token from the auth response in the Authorization Bearer header to call the MSactivator™ REST API.

curl -H 'Accept: application/json' -H "Authorization: Bearer TOKEN" -XGET 'http://<MSA IP or FQDN>/ubi-api-rest/user/customer-by-manager-id/1

Format

MSactivator™ API uses the JSON format.

Example API commands

For the full list of available commands, see the MSactivator™ API guide on your MSactivator™ instance: http://<MSA IP or FQDN>/swagger

User login

HTTP Request: /ubi-api-rest/auth/token

Method: POST

Parameter Name Type Description

username

String

User name

password

String

Password

Example:

{
	"username": "test",
	"password": "test1234567890"
}

Response:

{
	"token": "<TOKEN>",		(1)
	"message": "authenticated",
	"authenticated": "true",
	"userDetails": {
		"id": 18,

		... (2)

		"externalReference": "UBIG18",
		"login": "test",
		"firstname": "",
		"manageAllUsers": true,
		"name": "test",
		"sort": "NAME",
		"ldapAuthentication": false,
		"delegationProfilePerCustomer": {}
	}
}
1 the authentication token to use in the HTTP header of the REST API calls
2 the JSON response has been shortened for this documentation

Ping an IP address from the CoreEngine

HTTP Request: /ubi-api-rest/device/ping/{$ip_address}

Method: GET

Parameter Name Type Description

ip_address

String

The IP address to ping

Example:

/ubi-api-rest/device/ping/127.0.0.1

Response:

{
	"status": "OK",
	"rawJSONResult": "{\"sms_status\":\"OK\",\"sms_code\":\"\",\"sms_message\":\"--- 127.0.0.1 ping statistics ---\\n5 packets transmitted, 5 received, 0% packet loss, time 3999ms\\nrtt min/avg/max/mdev = 0.031/0.036/0.043/0.006 ms\"}",
	"message": "--- 127.0.0.1 ping statistics ---\n5 packets transmitted, 5 received, 0% packet loss, time 3999ms\nrtt min/avg/max/mdev = 0.031/0.036/0.043/0.006 ms"
}

Call microservice functions

HTTP Request: /ubi-api-rest/ordercommand/execute/{device_id}/{command_name}

Method: POST

Parameter Name Type Description

device_id

Long

The database identifier of the Managed Entity

command_name

String

One of CREATE, UPDATE, DELETE

body

String

the payload with the microservice parameters

Example:

/ubi-api-rest/ordercommand/execute/156/CREATE
{
	"simple_firewall": {
		"789": {
			"object_id": "789",
			"src_ip": "7.8.3.0",
			"src_mask": "255.255.255.0",
			"dst_ip": "8.8.3.0",
			"dst_mask": "255.255.255.0",
			"service": "http",
			"action": "deny"
		}
	}
}

Response:

{
	"commandId": 0,
	"status": "OK",
	"message": "access-list 789 extended deny object http 7.8.3.0 255.255.255.0 8.8.3.0 255.255.255.0 log\n"
}

Configuration variables

HTTP Request: /variables/{deviceId}/{name}

Method: GET

Parameter Name Type Description

deviceId

Long

Id of device (Number format) has to be higher than 0, Example = 3453

name

String

Name of the variable, Example = var1

Configuration

HTTP Request: /system-admin/v1/msa_vars

Method: POST

Body:

[
  {
    "name": "string",
    "lastUpdate": "string",
    "comment": "string",
    "value": "string"
  }
]

Workflow

HTTP Request: orchestration/service/execute/{ubiqubeId}

Method: POST

Parameter Name Type Description

ubiqubeId

String

Id of the subtenant. A combination of the tenant prefix and the subtenant database ID. Example UBI123.

serviceName

String

Relative path of the workflow

processName

String

Relative path of the process

Body:

the payload JSON contains the parameter to pass to the process thus depends on the variables of the workflow

[
  {
    "name": "string",
    "lastUpdate": "string",
    "comment": "string",
    "value": "string"
  }
]

Example: call the process "Create Instance" of the worklflow "Helloworld"

This workflow is part of the MSActivator mini-lab and maintained in a github repository.

POST

/ubi-api-rest/orchestration/service/execute/BLRA7?serviceName=Process/Tutorials/Helloworld/Helloworld&processName=Process/Helloworld/Process_create_instance

{"name":"jack"}