Best Practice | Endpoint Introspection

Using /describe

Adding "/describe" is a helpful way to extract essential information about a specific endpoint. For instance, if one takes the endpoint "/hcm-rest-api/rest/1/pyemployee," appending "/describe" to it as "/hcm-rest-api/rest/1/pyemployee/describe" will provide the following details:

Information about fields

This section lists all the attributes of the endpoint along with their data type, whether they can be updated or queried, and if they are mandatory or optional fields.

Information about finders

Here the output shows all the available finders for the specific endpoint, including the name of the finder and the queryable fields. Additionally, it specifies if the fields are optional or not.

{height="" width=""}
.
For the finder shown in the above image ("findByDate"), there are two optional fields that one could query on. Below shows one example:

Information on primary key

This section lists the primary key which identifies each unique record in the database.

Information on available actions

All enabled actions on this endpoint (GET, POST, PATCH, DELETE) are available.

Application Version lookup

The containers mimic CMiC product applications. Here is how to lookup version on file by resource container.

To validate the container version installed on the CMiC APi Server instance, append the endpoint name with /version

Here is an example, let's say we want to check the version for this URL

https://mobtest.cmiccloudr12.com/cmictestrti/hcm-rest-api/rest/1/pyemployee

In the example above the container is represented by hcm-rest-api/rest/1 and the endpoint is /pyemployee.

To check the version on this endpoint, remove the /pyemployee and replace with /version, then run the GET method to retrieve the version installed.

Request

GET https://mobtest.cmiccloudr12.com/cmictestrti/hcm-rest-api/rest/1/version

Response

{
    "items": [
        {
            "Version": "1.0.160292",
            "links": [
                {
                    "rel": "self",
                    "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/version/1.0.160292",
                    "name": "version",
                    "kind": "item"
                },
                {
                    "rel": "canonical",
                    "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/version/1.0.160292",
                    "name": "version",
                    "kind": "item"
                }
            ]
        }
    ],
    "count": 1,
    "hasMore": false,
    "limit": 5,
    "offset": 0,
    "links": [
        {
            "rel": "self",
            "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/version",
            "name": "version",
            "kind": "collection"
        }
    ]
}

Application containers

Following tables provides list of applications and their container urls: