Introduction

Apperian’s API is a REST API, which means that you can use standard HTTP methods (GET, POST, PUT, and DELETE) to retrieve, submit, change, and delete data. To ensure data privacy, the API is served over HTTPS; unencrypted HTTP is not supported.

How It Works

Each interface provides a set of API resources that let you perform various mobile application management tasks. Each resource has a URL (or endpoint) on the EASE server. To call a resource, you send an HTTPS GET, POST, PUT, or DELETE request to the appropriate URL, and the EASE server responds with JSON-formatted data. When you send a POST or PUT request, the body of data you submit must be sent as JSON by specifying a Content-Type of application/json in the HTTP header.

Your code can be written with any tools capable of sending HTTP requests. The examples in this reference use cURL, an open-source command line tool. If you want to use cURL to interact with the API during your development process, it is available at curl.haxx.se.

Base URL for API Resources

Each API resource has the same base URL. There is a different base URL for each EASE hosted production environment. If you are not sure which hosted production environment you should use, check with Apperian Customer Support at support@apperian.com.

Environment Base URL
North America https://na01ws.apperian.com/
Europe https://eu01ws.apperian.eu/

If you are working with an on premise or custom implementation of EASE, check with your IT administrator who manages the EASE installation to obtain the correct base URL.

API Version

Some resources include a v1 version only and others include both a v1 and v2 version. When you send a request to an Apperian API resource, you should include the version in the resource URL. For example:

https://na01ws.apperian.com/v2/applications/app_catalogs/

Pointing to a specific version ensures that your codebase is backwards-compatible in the event that Apperian releases a new version of a resource in the future.

When writing new code, always point to the latest version of a resource. If you have existing code that references a v1 version of a resource that now has a newer version available, the v1 resource will still work but you should update your code to point to the v2 version as soon as possible. Apperian will continue to support older versions for a period of time, but they will be deprecated in a future release. Any v1 resource that now has a v2 version available includes an Attention note in its documentation that identifies the new resource and the timeframe for deprecating the older version.

Authentication

When you send a request to an Apperian API resource, you need to provide a valid authentication token. You obtain this token by sending a POST request to one of the following resources:

  • /catalog/authenticate/: Request a token from this resource to authenticate a user for requests to the Catalog API, Downloads and Installs API, and Reviews API. These APIs require both user and device context.
  • /users/authenticate/: Request a token from this resource to authenticate a user or administrator for all other API requests. Other than the Catalog API, Downloads and Installs API, and Reviews API, all other Apperian API requests require user-context only.

In your request to either authenticate resource, you specify the user ID and password for a valid EASE user. EASE responds with a unique authentication token that you can then provide in the HTTPS header (as X-TOKEN: {token}) of one or more subsequent requests during the API session.

A token authenticates a specific user, so you will need to provide different tokens based on who you need to authenticate during the transaction. To call some API resources, you need to provide an authentication token for a user who has been assigned the “Administrator’ role. With other resources, you need to provide a token that authenticates the specific user for whom you want to perform a task. For example, if you want to list all the applications available to user123, then you need to obtain an authentication token for user123.

In this guide, each resource is flagged with an Authentication box under the resource header; it indicates whether the resource requires user and device context (use /catalog/authenticate) or just user context (use /users/authenticate), and whether you can can authenticate as any EASE user or need to authenticate as an EASE administrator.

Note

If you manage affiliated organizations, you can authenticate as an EASE administrator of the parent organization and then send API requests to perform functions in any of your affiliated organizations—without having to re-authenticate. For instructions on doing this, see Sending Requests for Affiliated (Child) Organizations. Note that you should avoid sharing an administrator account when you manage affiliated organizations, and should therefore create a separate administrator user account to use only with API requests.

Controlling GET Responses

When you send a GET request to the following resources, you can specify parameters to search, sort, and paginate the JSON data returned in the response:

  • GET /users
  • GET /applications
  • GET /groups

For instructions on searching, sorting, and paginating GET responses, see Controlling GET Responses.