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 |
|---|---|
Fetches site and subnet data from Active Directory and stores it in the ContentDistribution database as device tags using the Web API. | |
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 |
|---|---|---|
| GET | Retrieves a list of devices. |
| GET | Retrieves the single device by the id provided in the url. |
| 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 |
|---|---|---|
| GET | Retrieves a list of tags for the device specified |
| GET | Retrieves a list of tags for the device and category specified |
| GET | Retrieves a list of tags for the device, category and name specified |
| GET | Retrieves a single tag for the device, category, name and index specified |
| 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 |
|---|---|---|
| POST | Adds a single location resource (returns its unique identifier). |
| GET | Returns a specific location resource using its unique identifier. |
| GET | Returns a listing of all location resources. |
| DELETE | Removes a single location record using its unique identifier. |
| 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 |
|---|---|---|
| POST | Creates, view and delete pre-cached jobs. |
| 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.