REST API for managing license metrics
Use REST API requests to retrieve, create, change, and delete license metrics. From version 10.0.5, you can also manage metrics through the UI. See also, managing license metrics through UI.
Retrieval of license metrics
Use GET operation on api/sam/v2/metrics
element to request
information about license metrics defined or present in BigFix Inventory.
You must have the View Contracts and Manage Contracts permissions to use the
api/sam/v2/metrics
API.
Operation details | Descriptions |
---|---|
Operation | GET api/sam/v2/metrics |
Purpose | Returns list of license metrics and their details |
HTTP method | GET |
Resource URI | https://server_host_name:port_number/api/sam/v2/metrics?token=token |
Request content-type | application/json |
Response content-type | application/json |
Normal HTTP response codes | 200-ok |
Attribute | Possible values |
---|---|
id | Identifier of the license metric. For explanation of the returned values, see: Metric IDs and code names. |
code_name | Code name of the license metric. For explanation of the returned values, see: Metric IDs and code names. |
display_name | Name of the license metric. |
source_type | Source type of license metric. Value 2 means a custom metric and Values 0 and 1 mean a predefined metric. |
source_id | Source id of license metric |
- Request
-
https://localhost:9081/api/sam/v2/metrics?token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
{ "total": 3, "rows": [ { "id": -32603, "code_name": "CONCURRENT_USER", "display_name": "Concurrent User", "source_type": 1, "source_id": 27 }, { "id": -32470, "code_name": "VU_VALUE_UNIT", "display_name": "VU Value Unit", "source_type": 1, "source_id": 32 }, { "id": -32337, "code_name": "APPSERVER_CONNECTED", "display_name": "AppServer Connected", "source_type": 1, "source_id": 108 } ] }
Adding and updating license metrics
Adding license metrics
Use
POST operation on api/sam/v2/metrics
element to create new license
metric.
Operation details | Description |
---|---|
Operation | POST api/sam/v2/metrics |
Purpose | Creates new license metric |
HTTP method | POST |
Resource URI |
https://hostname:port/api/sam/v2/metrics? code_name=code_name&display_name=display_name&token=token |
Request content-type | application/json |
Response content-type | application/json |
Normal HTTP response codes | 200-ok |
Error HTTP response codes | 400 – "Bad Request" if a query parameter contains errors or if the metric with same metric code name or display name already present |
Response attributes
Attribute | Possible values |
---|---|
code_name | Code name of the metric, which is created |
display_name | Name of the metric created. |
source_type | Source type of license metric created. |
source_id | Source id of license metric created. |
error |
Reason for creation of metric failure. |
- Maximum length allowed for code_name and display_name attributes is 254.
- Attribute code_name should not have any spaces in between the words and can use "_" as word separator. All letters should be in upper case.
- Create metric using POST operation
- Request
-
POST https://localhost:9081/api/sam/v2/metrics?code_name=METRIC_POST&display_name=DISPLAY&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
200 ok Response body (JSON) { "id": 32468, "code_name": "METRIC_POST", "display_name": "DISPLAY", "source_type": 2, "source_id": 32468 }
- Creation of metric failed. Metric already exist.
- Request
-
POST https://localhost:9081/api/sam/v2/metrics?code_name=METRIC_POST&display_name=DISPLAY&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
400 Bad Request Response body (JSON) { "error": "Metric already present" }
- Creation of metric failed. Incorrect code name or display name.
- Request
-
POST https://localhost:9081/api/sam/v2/metrics?code_name=metric_post&display_name=DISPLAY&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
400 Bad Request Response body (JSON) { "error": "Metric code name or display name not proper" }
Updating license metrics
Use PUT operation on
api/sam/v2/metrics
element to update display name of already
existing metric.
Operation details | Description |
---|---|
Operation | PUT api/sam/v2/metrics |
Purpose | Updates metric display name for existing metric |
HTTP method | PUT |
Resource URI |
https://hostname:port/api/sam/v2/metrics? code_name=code_name&display_name=display_name&token=token |
Request content-type | application/json |
Response content-type | application/json |
Normal HTTP response codes | 200-ok |
Error HTTP response codes | 400 – "Bad Request" metric does not exist or display name length given to for
update is greater than 254 403 – “Forbidden”, trying to update non custom metric, which has source_type other than 2 |
Attribute | Possible values |
---|---|
code_name | Code name of the metric, for which update sent. |
display_name | Updated name of the metric. |
source_type | Source type of license metric updated. |
source_id | Source id of license metric updated. |
error |
Reason for display name update fail. |
- Update metric using PUT operation
- Request
-
PUT https://localhost:9081/api/sam/v2/metrics?code_name=CONCURRENT_USER&display_name=Updatedvalue&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
200 ok Response body (JSON) { "id": 27, "code_name": "CONCURRENT_USER", "display_name": "Updated value", "source_type": 1, "source_id": 27 }
- Metric update failed. Metric does not exist.
- Request
-
PUT https://localhost:9081/api/sam/v2/metrics?code_name=NOT_PRESENT&display_name=DISPLAY&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
400 Bad Request Response body (JSON) { "error": "Metric does not exist" }
- Metric update failed. Display name length is more than 254.
- Request
-
PUT https://localhost:9081/api/sam/v2/metrics?code_name=CONCURRENT_USER&display_name=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 2&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
400 Bad Request Response body (JSON) { "error": "Display name length is too long" }
- Metric update failed. Attempt to update non-custom metric.
- Request
-
https://localhost:9081/api/sam/v2/metrics?code_name= VU_VALUE_UNIT &display_name=Updatedvalue&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
403 Forbidden Response body (JSON) { "error": "VU_VALUE_UNIT metric update not allowed" }
Deleting license metric
Use DELETE operation on api/sam/v2/metrics
element to delete
license metric.
Operation details | Description |
---|---|
Operation | DELETE api/sam/v2/metrics |
Purpose | Deletes new license metric |
HTTP method | DELETE |
Resource URI |
https://hostname:port/api/sam/v2/metrics? code_name=code_name&token=token |
Request content-type | application/json |
Response content-type | application/json |
Normal HTTP response codes | 200-ok |
Error HTTP response codes | 400 – "Bad Request" if the metric not present 403- “Forbidden” if the metric is non custom metric, having source_type value other than 2 |
Response attributes
Attribute | Possible values |
---|---|
error | Reason for metric deletion failure |
Example HTTP conversation
- Metric deleted successfully
- Request
-
DELETE https://localhost:9081/api/sam/v2/metrics?code_name=TEST&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
200 ok Response body (JSON) { }
- Delete metric failed
- Request
-
DELETE https://localhost:9081/api/sam/v2/metrics?code_name=TEST&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
400 Bad Request Response body (JSON) { "error": "Metric does not exist" }
- Delete non-custom metric failed
- Request
-
DELETE https://localhost:9081/api/sam/v2/metrics?code_name= VU_VALUE_UNIT&token=6b884e39d8d34e05192c5d72dd6739607293b828
- Response
-
Response 403 Forbidden Response body (JSON) { "error": "VU_VALUE_UNIT metric delete not allowed" }