Skip to main content

1E 23.11 (SaaS)

Content Distribution Web API

Resource representations that are supported by the Content Distribution API for third party use.

Example scripts

ContentDistribution currently provides two example scripts:

Script

Description

Active Directory Single Site Script

Fetches site and subnet data from Active Directory and stores it in the ContentDistribution database as device tags using the Web API.

Custom Single Site script

Adds custom site and subnet data to the ContentDistribution database using the ActiveEfficiency Web API.

Supported resources

The following resource representations are supported by the Content Distribution Web API for third party use.

Devices

This is the primary resource representing hardware being discovered for example, desktops, servers or laptops. The following HTTP URI's and methods are supported for this resource:

URI

Method

Description

http://<server>/ActiveEfficiency/discovery/devices

GET

Retrieves a list of devices.

http://<server>/ActiveEfficiency/discovery/devices/{device id}

GET

Retrieves the single device by the id provided in the url.

http://<server>/ActiveEfficiency/discovery/devices

PUT

Adds or updates a single device.

Note

DELETE is not supported.

A device resource has the following properties:

Name

Type

Mandatory

Description

Id

unique identifier

No

A unique identifier that is assigned to the resource by the server. Needed to uniquely identify a device resource.

Identities

IList<DeviceIdentityResource>

No

A list of identities that the device is known by in other systems.

Fqdn

string

Yes

The FQDN of the device.

DomainName

string

No

The NetBIOS name of the domain (or the domain suffix for non Windows devices)

NetbiosName

string

No

The NetBIOS name of the device (or host name for non Windows devices).

Type

int

No

0: Unknown

1: Desktop

2: Laptop

3: Server

CreatedBy

string

No

The name of the client creating the resource. Currently not mandatory, but will change.

CreatedTimestamp

DateTime

No

The time in UTC when the web service created the resource

ModifiedTimestamp

DateTime

No

The last time in UTC when the resource was modified.

A device identity resource has the following properties:

Name

Type

Mandatory

Description

Source

string

Yes

Name of the identity.

Identity

string

Yes

Value of the identity. This is always represented as a string even if the external source represents it as another type (integer, GUID etc.)

AssignedUtc

DateTime

No

The date/time that the external system assigned this identity to the device.

Device Tags

A device tag represents a name-value pair that defines a certain attribute of the device. These attributes may extend the identity of the device or may be used in defining query based collections of devices. The following HTTP URI's and methods are supported for this resource:

Uri

Method

Description

http://<server>/ActiveEfficiency/discovery/devices/{device id}/tags

GET

Retrieves a list of tags for the device specified

http://<server>/ActiveEfficiency/discovery/devices/{device id}/tags/{category}

GET

Retrieves a list of tags for the device and category specified

http://<server>/ActiveEfficiency/discovery/devices/{device id}/tags/{category}/{name}

GET

Retrieves a list of tags for the device, category and name specified

http://<server>/ActiveEfficiency/discovery/devices/{device id}/tags/{category}/{name}/{index}

GET

Retrieves a single tag for the device, category, name and index specified

http://<server>/ActiveEfficiency/discovery/devices/{device id}/tags

POST

Adds a single device tag to the list of device tags, returning the created resource. Device tags are identified by category, name and index - they do not have an explicit id. If tag with the same category, name and index already exists, the value and the modified date get updated.

DELETE is not supported.

The device tag resource has the following public properties:

Name

Type

Mandatory

Description

Category

string

Yes

The category (namespace) for the tag. The category and name uniquely identify the resource. Category is mandatory. It must not be null, empty or only whitespace.

Name

string

Yes

The tag name. Name is mandatory. It must not be null, empty or only whitespace.

StringValue

string

Yes

The value represented as a string.

Type

int

Yes

Must be 0 (string), or 1 (date/time). If date/time, value must be in universal sortable format (http://msdn.microsoft.com/en-us/library/az4se3k1.aspx)

CreatedBy

string

No

The name of the client creating the resource. Currently not mandatory, but will change.

CreatedTimestamp

string

No

The UTC time when the web service created the resource.

ModifiedTimestamp

string

No

The last UTC time when the resource was modified.

Location

These location resources are used by Nomad to identify subnets contained within the same site. These are pre-populated by some out-of-band method (e.g. PowerShell script). They are not directly consumed by Nomad (the web service determines which Content Delivery resources to return based on the contents of the location section of its database).

URI

Method

Description

http://<server>/ActiveEfficiency/locations/

POST

Adds a single location resource (returns its unique identifier).

http://<server>/ActiveEfficiency/locations/{id}/

GET

Returns a specific location resource using its unique identifier.

http://<server>/ActiveEfficiency/locations/

GET

Returns a listing of all location resources.

http://<server>/ActiveEfficiency/locations/{id}

DELETE

Removes a single location record using its unique identifier.

http://<server>/ActiveEfficiency/locations/

DELETE

Removes all location records.

Location resources have the following public properties:

Name

Type

Mandatory

Description

Id

GUID

Yes

Unique identifier for this location (auto-generated).

Site

string

Yes

Name of Site that this Location belongs to. Arbitrary and used to find related Subnets.

Subnet

string

Yes

Subnet (for example, "10.0.10.0/24")

Pre-cached jobs

These content distribution job resources are used to manage pre-cached jobs and retrieve download notifications:

URI

Method

Description

http://<server>/ActiveEfficiency/ContentDistributionJobs/

POST

Creates, view and delete pre-cached jobs.

http://<server>/ActiveEfficiency/ContentDownloadNotifications/{id}/

GET

Retrieves download notifications

Content distribution job resources have the following public properties:

Name

Type

Mandatory

Description

Id

unique identifier

No

Identifier for the resource.

DeviceFqdns

Array of strings

Yes

List of device FQDNs

ContentItems

Array of content items

Yes

List of contents. Must include the ID and version of the content.

UserData

XML

No

Additional details about job.

Content download notifications have the following public properties:

Name

Type

Mandatory

Description

ContentId

string

Yes

Identifier for the content.

Version

string

Yes

Version of the content.

Hash

string

No

SHA-256 hash to verify integrity of files inside content

Managing large amounts of data

ODATA is an open standard that allows clients to consume data feeds in an open format and was designed for this purpose. The web service supports ODATA so that the clients can ask for pages of data. Assuming that the web service contains 1000 devices, the following are examples of how ODATA helps us:

Without ODATA

Without ODATA, the following url returns 1000 devices in one go; no good if the client limits the buffer size:

http://<server>/ActiveEfficiency/devices [GET] ;

returns 1000 devices in one go

With ODATA

ODATA supports the keyword top and skip which allows you to implement the following loop:

http://<server>/ActiveEfficiency/devices?$top=100&$skip=0;

returns the first 100 devices

http://<server>/ActiveEfficiency/devices?$top=100&$skip=100;

returns the next 100 devices

http://<server>/ActiveEfficiency/devices?$top=100&$skip=200;

returns the next 100 devices and so on.