IOx

Cisco Fog Director REST API

This document describes the Cisco Fog Director API and some of the common tasks that you can perform with it.

Overview

Cisco Fog Director enables the management of IOx nodes at scale. It provides easy and intuitive workflows that you use to perform activities that include installing, starting, stopping, upgrading, and monitoring apps across multiple Cisco devices.

For more detailed information, see “Cisco Fog Director Reference Guide”.

For an exhaustive list of all available REST apis on Fog Director, see <FD IP Address>/swagger-ui/index.html. If you do not have a Fog Director installation handy, you could reserve an IOx Devnet sandbox at (https://developer.cisco.com/docs/sandbox/#!iot/featured-labs).

However, we recommend that you first review this document for explanation of key concepts regarding the design and use of the API.

Key Concepts

We recommend that you become familiar with Cisco Fog Director before you read the following sections. A familiarity with Cisco Fog Director can help you to understand the concepts that this document describes. In addition, taking a look at the Network tab in your browser while executing certain Cisco Fog Director operations can help you to determine the appropriate API method for a task. (You can access the Network tab in some browsers by right-clicking a web page, and then choosing Inspect Element > Network.)

App Lifecycle

Each app has a life cycle in Cisco Fog Director. The app starts out in a draft state when you add it to Cisco Fog Director. In this state, the app is not yet available for installation on devices. An app remains in this state until it is published. Publishing an app makes it available to install on devices.

Before you can install an unpublished app on a device by using the API, you must create a myapp endpoint for the app. This endpoint points to the most recently published version of the app. The system retains the myapp endpoint even if the app is uninstalled from all devices.

After you install an app on at least one device, it becomes an installed app.

See the appmgr/apps APIs for app workflow and lifecycle actions section below.

Versioning

An app can have multiple versions. When a new version of an installed app becomes available, you can upgrade the app. The upgrade process includes uploading the app for Cisco Fog Director and then upgrading devices with the new app version.

Authentication

The API requires you to authenticate with Cisco Fog Director by using the Basic Authentication method. This method passes a base64 encoded username:password string through the Authorization header for each API request

The following example shows how to issues a request that returns a token. The token must be included in the in the X-Token-Id header for subsequent API calls.

Code Snippet
Copycurl -k -X POST -H "Authorization:Basic YWRtaW46Y2lzY28=" https://10.78.106.176/api/v1/appmgr/tokenservice

After a token is used, it must be deleted with a DELETE request to the same REST endpoint that was used to request it.

See sample code

REST Endpoints

The following are some of the more important REST endpoints that you use with the API:

  • api/v1/appmgr/localapps-Used to add or upgrade apps.
  • api/v1/appmgr/devices-Used add, modify, or delete devices from Cisco Fog Director.
  • api/v1/appmgr/myapps-All app lifecycle actions for devices start from this endpoint.
  • api/v1/appmgr/jobs-Used to query for outstanding actions, the statuses of these actions, and the devices that these actions involve.

Useful Workflows

The following sections show how to use the API to perform some of the more common workflows in Cisco Fog Director.

Device Workflows

Adding a Device

The following is an example of using the API to add a device to Cisco Fog Director:

Code Snippet
Copyurl = "https://%s/api/v1/appmgr/devices" % ip
headers = {'x-token-id':token,'content-type': 'application/json'}
data = {'port':'8888','ipAddress':device_ip,'username':'t','password':'t'}
r = requests.post(url,data=json.dumps(data),headers=headers,verify=False)

See sample code

Tagging a Device

A tag is a brief descriptive label that you can create in Cisco Fog Director and then assign to a device.

The following is an example of using the API to create a tag:

Code Snippet
Copytag_url="https://%s/api/v1/appmgr/tags" % ip
headers = {'x-token-id':token,'content-type': 'application/json'}
data = {'name':'withtag'}
r = requests.post(tag_url,data=json.dumps(data),headers=headers,verify=False)

The following is an example of using the API to assign a tag to a device:

Code Snippet
Copytag_device_url="https://%s/api/v1/appmgr/tags/%s/devices" % (ip,str(tagid))
headers = {'x-token-id':token,'content-type': 'application/json'}
data = {'devices':[deviceid]}
r = requests.post(tag_device_url,data=json.dumps(data),headers=headers,verify=False)

See sample code

Searching Devices

The devices end point provides several query parameters that you can use to search for devices.

The following is an example of using the API to search for a device that is assigned a designated tag:

Code Snippet
Copyurl = "https://%s/api/v1/appmgr/devices?limit=10000&offset=0&searchByTags=%s" % (ip,tag_to_search)
headers = {'x-token-id':token,'content-type': 'application/json'}
r=requests.get(url,headers=headers,verify=False)

See sample code at the following URLs:

Sample one Sample two

The following are examples of using the API to search for a device that has a designated reachability status.

The /api/v1/appmgr/devices/reachabilityCount operation provides several HATEOS links to query devices based on their reachability statuses. Here are some examples:

Code Snippet
Copy{devices: {href: "/api/v1/appmgr/devices?searchByReachabilityLessThan=day"}, count: 1}
{devices: {href: "/api/v1/appmgr/devices?searchByReachabilityLessThan=month"}, count: 0}
{devices: {href: "/api/v1/appmgr/devices?searchByDeviceStatus=offline"}, count: 0}

See sample code

App Workflows

Adding an App

To add an app to Cisco Fog Director use the HTTP POST action to post into the localapps endpoint as shown in the following example:

Code Snippet
Copyurl = "https://%s/api/v1/appmgr/localapps/upload" % ip
headers = {'x-token-id':token}
r = requests.post(url, headers=headers, files={'file':open('SampleApp.tar.gz','rb')}, verify=False)

See sample code

Publishing an App

Publishing an app makes it available to install on devices. You can publish an app by changing its published field to true and then using the HTTP PUT action. These operations are performed on a particular version of the app. Here is an example:

Code Snippet
Copyapps['data'][index]['published'] = True
url = "https://%s/api/v1/appmgr/localapps/%s:%s" % (ip, appid, appversion)
headers = {'x-token-id':token,'content-type': 'application/json'}
data = json.dumps(apps['data'][index])
r=requests.put(url,headers=headers,data=data, verify=False)

See sample code

App Lifecycle Actions

The following are examples of using the API to perform various common lifecycle actions for an app.

Installing an App on a Set of Devices

To install an app on a set of devices , first create a myapp endpoint as shown in the following example:

Code Snippet
Copyurl="https://%s/api/v1/appmgr/myapps" % ip
headers = {'x-token-id':token,'content-type': 'application/json'}

data =	{"name":"TestRP","sourceAppName":"c36d727c-e9c5-46ed-bc7e-cbdd5cf49786:1.0", "version":"1.0","appSourceType":"LOCAL_APPSTORE"}

r = requests.post(url,data=json.dumps(data),headers=headers,verify=False)

After the myapp endpoint is created, use an HTTP POST action on that endpoint to install the app on selected devices. This action includes a payload that specifies the resource profile, networking options, serial port mapping, and configuration options that are used when the app is installed.

See sample code

Uploading App Data Files When Installing an App

If you want to upload one or more app data files when installing an app, first upload the app data files to the Cisco Fog Director host. For more information about app data files, see the Upload App Data Files to Multiple Devices for an Installed App section below.

Use the following API call to do so. Replace appid with the identifier of the app for which to upload the app data file, and replace version with the version of that app.

POST /api/v1/appmgr/localapps/{appid:version}/localAppdata

Then, when using the API to install the app, add an appDataInfo section under the deploy payload. This section includes the file names of the app data files that you uploaded to Cisco Fog Director.

The following sample code that shows the REST API call to upload app data files locally to Cisco Fog Director when installing the app:

See sample code

Configuring package_config.ini, Resource Profiles, Serial Port Mapping, and Networking Options During App Installation

This action is performed on the myapps endpoint, and maps resource profile options, serial port options, and network interface options to each device in an array of devices.

Code Snippet
Copyurl="https://%s/api/v1/appmgr/myapps/%s/action" % (ip,myapp_details['myappId'])
headers = {'x-token-id':token,'content-type': 'application/json'}
data = {
    "deploy":
        {
            "config":{'default':{'abc':'newtext2'}},
            "metricsPollingFrequency":"3600000",
            "startApp":True,
            "devices":[
                {
                    "deviceId":"7",
                    "resourceAsk":{
                        "resources":{
                            "profile":"custom","cpu":100,"memory":32,
                            "devices":[{type: "serial", label: "HOST_DEV1", device-id: "/dev/ttyS1"}], "network":[{"interface-name":"eth0","network-name":"iox-bridge0"}]
                        }
                    }
                }
            ]
        }
}


r = requests.post(url,data=json.dumps(data),headers=headers,verify=False)

See sample code

Starting, Stopping, Uninstalling an App From All Devices

The myapp action shown above also can be used to start, stop, upgrade, or uninstall an app from all devices on which it is installed.

See sample code

Retrying a Failed Install, Configuration, or Uninstall Action

You can use a {redeploy: {devices: [10]}} payload with the myapp/{myappId}/action REST endpoint to retry an app deploy or uninstall action.

Updating the Configuration for an App on Multiple Devices After Installing the App

The following is an example of updating the configuration for an app that is installed on multiple devices:

Code Snippet
Copyurl="https://%s/api/v1/appmgr/myapps/%s/action" % (ip,myappid)
data={'updateConfig':{'restart':'true','devices':devices_list,'config':{'default':{'abc':'newtext2'}}}}
r = requests.post(url3,data=json.dumps(data),headers=headers,verify=False)

Upload App Data Files to Multiple Devices for an Installed App

An app data file is any file that an app requires. These files are stored in the /data/appdata directory on each device’s app container. An app data file size must be less than the available disk space for the app for which the file is to be uploaded. If you upload an app data file to a directory in which a file with the same name exists, the existing file is overwritten.

To upload app data files on multiple devices on which an app is installed, use the following API call.

POST /api/v1/appmgr/myapps/{appid}/appdata

This call includes the following parameters in the payload: - files—Required. A list of app data files to be uploaded.

  • devices—Required. A list of IDs of devices to which to upload the app data files.

  • deleteAllAppdata—Optional. Default value is false. Set this parameter to true if you want files and subdirectories that are in the /data/appdata directory to be deleted before an app data file uploads.

  • newfilenames—Optional. Names to which to change the names of the files that you want to upload. If you do not specify file names, original file name is used.

  • filepaths—Optional. Names of directories under the /data/appdata directory on a device on which to upload the app data files. If these directories do not exit, they are created. If no filepath is provided, files are uploaded under the /data/appdata directory by default.

The number of newfilenames or filepaths provided should match the number of files. The order in which you specify the names or paths corresponds to the order in which you specify the app data files. If some files require new file names or paths but others do not, leave the values empty at the respective indices for files that do not require new names or paths. See the sample code at the link below for examples.

See sample code

The following example shows using the Postman tool to upload app data files on multiple devices on which an app is installed:

Postman

Alerts

Fog Director generates alerts in various situations. An alert is information that the system collects and provides when it detects certain issues with an app or device.

The alerts can be accessed at the /api/v1/appmgr/alerts endpoint.

Here are some of the conditions when alerts are raised.

• App Status — An app state mismatch situation occurs when the state of the app (Running, Stopped) is not the state that Fog Director expects. This could typically happen when the app changes state abruptly OR when its state is changed outside of Fog Director

• App Health— When the health script bundled with the App reports a non-zero return value.

• App Configuration—Configuration of the app does not match the app configuration settings on the device. This situation can occur if the app configuration is modified outside of Cisco Fog Director.

• App Resource—Resources of the app do not match the app resource settings on the device. This situation can occur if the app resources are modified outside of Cisco Fog Director.

• Device Reachability—Cisco Fog Director cannot contact the device even after the configured number of attempts. In this situation, there is one Device Reachability alert for each app that is installed on the device.

• Memory Consumption—During the last hour, an app has consumed more than 95% of the memory that is configured.

• Disk Consumption— During the last hour, an app has consumed more than 95% of the disk space that is configured.

• CPU Consumption— During the last hour, an app has consumed more than 95% of the CPU resources that is configured.

• App read rate—App has read data from the disk on a device at a rate faster than the maximum read rate threshold that is configured for the device.

• App write rate—App has written data to the disk on a device at a rate faster than the maximum write rate threshold that is configured for the device.

Code Snippet
Copyurl = "https://%s/api/v1/appmgr/alerts?limit=10&offset=0&searchByAlertStatus=%s" % (ip,alert_status)
headers = {'x-token-id':token,'content-type': 'application/json'}
r=requests.get(url,headers=headers,verify=False)

Audit

The audit endpoint /api/v1/appmgr/audit provides information about app state change events, who performed them, when they were performed and what the operation was. Some of the audited operations include app start, stop, docker layer cleanup, configure, app data upload, install, uninstall and reallocate resources. These audit information can be filtered by device serial id, by app and version or even by the user who performed it.

Code Snippet
Copyurl = "https://%s/api/v1/appmgr/audit?limit=10&offset=0&searchByAction=%s" % (ip,app_operation)
headers = {'x-token-id':token,'content-type': 'application/json'}
r=requests.get(url,headers=headers,verify=False)

App Installation Summary

The summaryState endpoint /api/v1/appmgr/myapps/{myAppId}/summaryState provides a summary of actions that are currently taking place in the myapp endpoint. HATEOS links on the response can help you drill down to a specific set of devices.

App Monitoring

You can obtain the following monitoring information for an app as shown in the referenced sample code:

appmgr/apps APIs for App Workflow and Lifecycle Actions

In previous Cisco IOx releases, the API used the URLS /api/v1/appmgr/localapps/{localAppId:version} and /api/v1/appmgr/myapps/{myAppId} for app workflow and lifecycle actions.

Beginning with Cisco IOx Release 1.6.0, some actions can be invoked through the API /api/vi/appmgr/apps/{localAppId:version}.

In all requests except for app package upgrade, if the version is not specified, the latest version of the app is used. For app package upgrade, the version must be specified in the URL.

New App Upload

Upload and publish an app POST /api/v1/appmgr/apps --header “x-publish-on-upload”=true //default

App Lifecycle Action

Actions: deploy, start, stop, undeploy, updateConfig, update, redeploy, or reallocateResources

POST /api/v1/appmgr/apps/localAppId:version/action --header=“x-tag-with-app-name”=true” //default

  • If version is not specified, the latest published version of the app is used
  • For the install action, including the header “x-tag-with-app-name”=true (default is true) creates a tag with app name (if it does not exist) and assigns this tag to all non-readonly devices that are managed by Cisco Fog Director

App Package Upgrade

Upload and publish an app POST /api/v1/appmgr/apps/localAppId:version/packages --header “x-publish-on-upload”=true //default If version is not specified, an APP_NOT_FOUND error is thrown

App Package Delete

Unpublish and delete an app DELETE /api/v1/appmgr/apps/localAppId:version --header “x-unpublish-on-delete”=true //default

  • If app is not installed on any devices, myapp endpoint is removed
  • If version is not specified, the the latest published version of the app is unpublished

The following sample code shows the app workflow and app lifecycle actions: See sample code

Device Specific App Actions

You can perform the following device specific actions for an app as shown in the referenced sample code:

Next