Skip to main content
Version: Release 23.1

How to Find Identifiers for REST API

To use the Release REST API, you need to know the unique identifiers for templates, releases, phases and tasks. This topic explains where you can find them.

Releases and templates​

Both releases and templates have an ID of the form Applications/ReleaseXXXXXXX, where XXXXXXX is a seven-digit number, all IDs start with Applications/. If you are using organized templates and releases in folders, their IDs will be of the form Applications/FolderXXXXXXXXX-FolderXXXXXXXXX-ReleaseXXXXXXX.

The fastest way to find the ID of a template or release is to open it in a browser and look at the URL in the location bar. Take the last part of the URL and prefix it with Applications. If the template or release is in a folder, you must also replace the hyphens (-) with forward slashes (/).

In these examples, the IDs are Applications/Release2994650 and Applications/Folder608123241/Folder283360226/Release482440157.

URL for template

URL with folders

Using the ID in a REST call​

After you have the ID, you can use it in a REST call. For example, to get the contents of a release, use:


    GET http://localhost:5516/api/v1/releases/Applications/Release9324610
    GET http://localhost:5516/api/v1/releases/Applications/Folder608123241/Folder283360226/Release482440157

Phases and tasks from the release response​

Phase and task IDs can be found in the response of the REST call that gets the contents of a release or template.

Inspect the contents of the release JSON object. The release ID is in the id field. All phases in the release are stored as a list in the phases property. In turn, the phases contain their tasks in the tasks property.

Here is an example:

{
    "id": "Applications/Release9324610",
    "type": "xlrelease.Release",
    "title": "Configure Release",
    ...
    "phases": [
        {
            "id": "Applications/Release9324610/Phase2437552",
            "type": "xlrelease.Phase",
            "title": "Setup mail server",
            ...
            "tasks": [
                {
                    "id": "Applications/Release9324610/Phase2437552/Task3066132",
                    "type": "xlrelease.Task",
                    "title": ""Configure email address and mail server",
note

IDs are hierarchical. The ID of the task in this example is Applications/Release9324610/Phase2437552/Task3066132, not Task3066132.

The following is an example that uses the task ID in a REST call:

GET http://localhost:5516/api/v1/tasks/Applications/Release9324610/Phase6441318/Task2674539

Getting IDs by title​

It is also possible to get a release, phase, or task by querying it by its title. Titles are not unique in Release. Releases may have duplicate names, as well as tasks in the same phase. So "by title" queries will always return a list of possibilities.

The following example finds all tasks that have the title "Configure email address and mail server" in the release with ID Applications/Release9324610:


    http://localhost:5516/api/v1/tasks/byTitle?taskTitle=Configure%20email%20address%20and%20mail%20server&releaseId=Applications/Release9324610

For more information, see REST API