API Overview

On this page

The Alloy Navigator API is a web interface that any HTTP client can call. The routes that read data, run workflow actions and functions, and handle attachments must be called over HTTPS. Responses use JSON unless the request's Accept header asks for XML; attachment downloads return the file content. Reading data runs queries over database views, and objects are created and changed only by running workflow actions.

The base URL

Every route of the API hangs off one base URL: the root of the API's IIS application. An API published in a virtual directory named api on the default HTTPS binding has the base URL https://<host>/api/. The routes that read data, run workflow actions and functions, and handle attachments are each reached as <base>/<route>, <base>/V1/<route>, or <base>/V2/<route>; see Versions.

When the instance does not use Windows authentication, the two token endpoints, token and externalToken, sit directly at the base URL and take no version segment. When the instance uses Windows authentication, neither token endpoint exists, and a call carries the caller's Windows credentials instead of a bearer token. See Authentication.

Find the base URL in the Web Configuration tool

  1. In the Web Configuration window, select the API instance in the tree. Each IIS site that has an HTTP or HTTPS binding is a top-level node, and each application under it is a child node named after its virtual directory.
  2. On the instance's information page, headed Alloy Navigator API, read the URL: line in the Web category.

The URL: value is a link: selecting it opens the address in the default browser.

Find the base URL in the Admin Center

In the Admin Center, the same URL appears in the URL field on the API instance's General tab.

The default page

The base URL itself, requested without credentials, returns a default page. The page shows the product name and version and the authentication type the instance is configured to use, and it links to the online API user guide. You can use this page to check which version an instance runs without signing in.

HTTPS

Every call to a route that reads data, runs a workflow action or function, or handles attachments must use HTTPS. A call made over plain HTTP is refused with status 505 HTTP Version Not Supported and the message "HTTP protocol is not supported." For the other checks a request must pass, see Requests and Responses.

Versions

The API has two versions, v1 and v2. A URL that names no version uses v2. v2 has every route of v1 plus one route of its own, GET <base>/V2/GetAppConfig?par_app_name=<application name>, which returns the configuration stored for that application. For how the server selects a configuration, see Mobile App Configuration. Because the route that lists objects of a class puts the class name in the first path segment, v1 and v2 are reserved there and never address an object class.

The version changes exactly three behaviors, all of them about HTML field pairs:

  • Naming a field in a read. On v2, a field you list, filter on, or sort by that is the plain-text half of an HTML field pair is redirected to the HTML half.
  • Reading one object. On v1, the value of an HTML field is converted to plain text.
  • Writing an HTML field. A plain-text field name that belongs to an HTML pair is written to the HTML field. On v1, the submitted value is HTML-encoded; on v2, it is stored as supplied, so v2 accepts HTML.

No direct CRUD

The API has no direct create, update, or delete of an object. Reading data uses queries over database views. An object is created or changed only by running a workflow action:

  • POST <base>/ runs a create action.
  • POST <base>/Object/{objectId}/Action/{actionId} runs a task action against an existing object.

The route decides which kind of action is expected. A task action sent to POST <base>/, or a create action sent to the action route, fails with "Cannot process the request. Requested action <event id> is of unexpected type."

GET <base>/Object/{objectId}/Action/{actionId}/Check evaluates whether an action is available without running it, and POST <base>/function/{functionId} runs a global workflow function, with no object context.

No route deletes an object. Attachments have their own routes on an object: they add attachments, change an attachment's description, and remove an attachment.

Testing tools

No client library, SDK, machine-readable API description, sample scripts, or test tool ships with the API. Any HTTP client can call it.

For worked requests and a PowerShell Incident-creation script, see Examples.

Besides the default page, these routes answer without credentials:

Route Returns
GET <base>/lifecycle/health A {version, startTime} object: the product version and a UTC time. The time is recorded when the lifecycle service is first used, not when the process starts. The route also accepts cross-origin requests.
POST <base>/Ver/GetApiVersion The version number as major.minor.build.
GET <base>/V1/ProductVersion The version number as major.minor.build.