- 16 Feb 2024
- 1 Minute to read
- Print
- DarkLight
Best Practice | Endpoint Introspection
- Updated on 16 Feb 2024
- 1 Minute to read
- Print
- DarkLight
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
Each CMiC endpoint roll up into a container. The containers mimic CMiC product applications.
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:
Product | Container URL |
---|---|
GENERAL LEDGER | glrestapi/rest/1 |
ACCOUNTS PAYABLE | ap-rest-api/rest/1 |
ACCOUNTS RECEIVABLE | ar-rest-api/rest/1 |
JOB COST | jc-rest-api/rest/1 |
JOB BILLING | jb-rest-api/rest/1 |
EQUIPMENT MANAGEMENT | em-rest-api/rest/1 |
FIXED ASSETS | fa-rest-api/rest/1 |
INVENTORY MANAGEMENT | ci-rest-api/rest/1 |
MATERIAL SALES | ms-rest-api/rest/1 |
HUMAN CAPITAL MANAGEMENT | hcm-rest-api/rest/1 |
CHANGE MANAGEMENT | cm-rest-api/rest/1 |
OPPORTUNITY MANAGEMENT | om-rest-api/rest/1 |
PROJECT MANAGEMENT | pm-rest-api/rest/1 |
PM DOCUMENTS | pm-doc-rest-api/rest/1 |
PURCHASE ORDERS | po-rest-api/rest/1 |
PREVENTATIVE MAINTENANCE | prm-rest-api/rest/1 |
ENTERPRISE CONTENT MANAGEMENT | ecm-rest-api/rest/1 |
SYSTEM DATA | sys-rest-api/rest/1 |