General Guidelines and Conventions

Parameter Formats

The HTTP requests use two types of parameters:

•Path parameters

•Query parameters

Path Parameters

Path parameters continue the URI path using a slash (/) for a separator. For example, to get details for a device, you specify its device uuid with a path parameter. The following shows the URI format for this request, and an example:

https://{host-name}/api/v1/dm/devices/{deviceuuid}

https://<Ivanti EPMM>/api/v1/dm/devices/4239b999-46e3-423b-b808-54fff69b544c

If a request uses path parameters, they are specified in the URI format for the request.

Query parameters

Query parameters are included in the URI path using a question mark or ampersand (? or &). For example, to retire a device, after specifying the device uuid as a path parameter, you specify a reason as a query parameter. The following shows the URI format for this request, and an example:

https://{host-name}/api/v1/dm/devices/retire/{deviceuuid}

https://<Ivanti EPMM>/api/v1/dm/devices/retire/c097c9e2-c82e-40f6-9e69-a0478c4fcee0?reason=AnyReasonTextYouChoose

The first query parameter is preceded by a question mark (?), using the following format:

?parameterName=parameterValue

Subsequent query parameters are preceded by an ampersand (&), using the following format:

&parameterName=parameterValue

For example, to get all the Android devices that have a particular application installed, use the following request:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=Frog%20Toss!_017%201.0&platform=A

Note: If a parameter is not shown in a request’s URI format with a slash, it is a query parameter; the URI format for a request shows only the path parameters. The description that follows each URI format provides information on the query parameters, if any.

Date Formats

Many API calls include start and end dates in the request. In general, the dates are optional. If dates are not included, all available records will be returned. If start and end dates are included in the request, only records within the date range will be returned.

Dates can be in the following formats

•Jan 1 2010

•January 1, 2010

•January 1, 2010, 00:00:00

•UTC format: YYYY-MM-DDThh:mm:ssTZD

For example: 2010-03-10T15:04:06+00:00 which is March 10, 2010 3:04:06 PM

•Alternate format: MM-DD-YYYY hh:mm:ss

For example: 03-12-2010 13:23:12 which is March 12, 2010 1:23:12 PM

Phone Number Formats

Many API calls require a phone number in the request. The following rules apply to an input phone number:

•Enter numbers only.

•Do not include a country code.

•Do not include parenthesis, dashes, periods, or other special characters.

HTTP request methods

Depending on the HTTP request, use one of the following HTTP request methods:

•Get – Use for requests that retrieve information from Ivanti EPMM.

•Put – Use for requests that change information on Ivanti EPMM.

•Post – Use for the bulk requests that perform actions on many devices, or for requests that provide substantial information on Ivanti EPMM.

Each request description specifies which HTTP request method to use.

Response Formats

Requests to the API can return xml or json, based on the request headers.

•For xml output, set the ‘Accept’ header in the request to ‘application/xml’.

•For json output, set the ‘Accept’ header in the request to ‘application/json’.

HTTP Response Codes

Responses from the API use the codes listed below. In addition, a “Success” message is shown for successful method executions. When method executions fail, a descriptive error message is displayed.

•200 OK: Success

•400 Bad request: The request was invalid. The accompanying error message in the output explains the reason.

•401 Unauthorized: Authentication to the API has failed. Authentication credentials are missing or wrong.

•404 Not found: The requested resource is not found. The accompanying error message explains the reason.

•405 Method Not Allowed: The HTTP request method that was specified is not the correct method for the request.

•500 Internal Server Error: An internal server error has occurred while processing the request.

•502 Bad Gateway: The Ivanti EPMM server is not reachable.

Using offset and limit Parameters to Cycle through Records

Some requests result in responses that contain many records. For example, the request for the list of all devices on which a specific application is installed can match hundreds or thousands of devices.

To return more than the first 100 records, these APIs support the limit and offset query parameters. These parameters allow you to get successive sets of records in successive responses.

Specifically, use these query parameters to do the following:

•Limit the number of records returned in the response to a number you choose, using the query parameter limit.

For example, the following request returns the first 50 devices that have the LinkedIn app installed:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50

•Specify the index of the first record to return in the response, using the query parameter offset.

The value is zero-based. For example, the following request returns 50 devices, starting with the 101^st device:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=100

The offset parameter defaults to 0. Therefore, both of the following requests return 50 devices, starting with the first device:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=0

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50

Therefore, to get successive sets of records in successive responses, increase the offset value by the limit value in each request. For example:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=0

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=50

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=100

For the API that gets the devices that have a particular app installed (Get Devices by Application Name), you can also set limit to -1 to get all the devices in one response. For example:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=-1

The following table summarizes the limit and offset query parameters.

Query parameter	Description	Default value	Special value
limit	Maximum number of records to show in the response.	100 Note: This default value applies only to APIs that support the limit query parameter. Other APIs always return all applicable records in the response.	-1 Shows all records in the response. Note: This special value only applies to the apps/inventory/app API.
offset	Zero-based index of first record to show in the response	0

Query parameter

Description

Default value

Special value

limit

Maximum number of records to show in the response.

100

Note: This default value applies only to APIs that support the limit query parameter. Other APIs always return all applicable records in the response.

-1

Shows all records in the response.

Note: This special value only applies to the apps/inventory/app API.

offset

Zero-based index of first record to show in the response

Device and User Identifiers

The requests and responses use identifiers for devices and users.

Every time a user or a device is created, Ivanti EPMM internally generates a unique identifier, called a “uuid”. Each device gets a unique uuid. Because a single user can have multiple devices, each user gets a unique uuid, independent of any devices used.

Other IDs are used for other purposes, such as identifying a network, and are described in the APIs.

Operating System Dependencies

Refer to the Administrator’s Guide for an up-to-date matrix which displays supported features by operating system and platform. If a particular feature is not supported by an OS, the feature API will not return a valid response.

Supported Browsers and Recommended Plugins

FireFox and Chrome are the supported browsers. Internet Explorer is not supported. Plugins like Poster for FireFox and Advanced REST Client for Chrome are recommended for interacting with the http server; simply submitting a URI in the browser does not consistently result in a properly rendered response.

General Practice

All the requests are wrapped in WebServiceRequest, and the responses are wrapped in WebServiceResponse. startDate and endDate from the request are returned in the response.