Accessing Resources Using Named URLs

Oracle Linux Automation Manager provides two groups of named-URLs that you can use to access and manage resources with. These named-URLs are located here: /api/v2/settings/named-url/. The named-URL groups are:

NAMED_URL_FORMATS
NAMED_URL_GRAPH_NODES

NAMED_URL_FORMATS is a read only key-value pair list of all available named URL identifier formats. The NAMED_URL_FORMATS syntax is as follows:

/organizations/<name>
/teams/<name>++<organization.name>
/credential_types/<name>+<kind>
/credentials/<name>++<credential_type.name>+<credential_type.kind>++<organization.name>
/notification_templates/<name>++<organization.name>
/job_templates/<name>++<organization.name>
/projects/<name>++<organization.name>
/inventories/<name>++<organization.name>
/hosts/<name>++<inventory.name>++<organization.name>
/groups/<name>++<inventory.name>++<organization.name>
/inventory_sources/<name>++<inventory.name>++<organization.name>
/inventory_scripts/<name>++<organization.name>
/instance_groups/<name>
/labels/<name>++<organization.name>
/workflow_job_templates/<name>++<organization.name>
/workflow_job_template_nodes/<identifier>++<workflow_job_template.name>++<organization.name>
/applications/<name>++<organization.name>
/users/<username>
instances/<hostname>

For example, this cURL request returns details about the team1 that is part of org1:

curl -i -H "Authorization: Bearer pVQoc51Apt4LNrXrNzoSbaMCDzjK8B" -X GET https://192.102.118.107/api/v2/teams/team1++org1

NAMED_URL_FORMATS exclusively lists every resource that can have named URL. NAMED_URL resources each have a named_url field which in the detailed view that represents the object-specific named URL. You can also view an object's related URLs. For example, if /api/v2/res_name/obj_slug/ is valid, /api/v2/res_name/obj_slug/related_res_name/ is valid.

Every named URL resource has related field named_url that displays that object's named URL. You can copy and paste that field for your own use. For example, the following shows team details with the ID 2 in the REST API browser at the /api/v2/teams/2/. In the related object, the named_url field shows the named url with a named_url value:

"id": 2,
    "type": "team",
    "url": "/api/v2/teams/2/",
    "related": {
        "named_url": "/api/v2/teams/team2++org1/",
        "created_by": "/api/v2/users/1/",
....

An important aspect of generating a unique identifier for named URL has to do with reserved characters. Because the identifier is part of a URL, the following reserved characters are encoded by percentage symbols: ;/?:@=&[]. For example, if an organization is named ;/?:@=&[], its unique identifier should be %3B%2F%3F%3A%40%3D%26%5B%5D. Another special reserved character is +, which is not reserved by URL standard but used by the named URL functionality to link different parts of an identifier. It is encoded by [+]. For example, if an organization is named [+], its unique identifier is %5B[+]%5D, where original [ and ] are percent encoded and + is converted to [+].

NAMED_URL_GRAPH_NODES is another read-only list of key-value pairs that exposes the internal graph data structure that Oracle Linux Automation Manager uses to manage named URLs. This is not intended to be human-readable but should be used for programmatically generating named URLs. An example script for generating named URL given the primary key of arbitrary resource objects that can have a named URL, using info provided by NAMED_URL_GRAPH_NODES, can be found in GitHub at https://github.com/ansible/awx/blob/devel/tools/scripts/pk_to_named_url.py.