10.0.4 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.

PermissionYou must have the View Contracts and Manage Contracts permissions to use the api/sam/v2/metrics API.

Table 1. Operation descriptions
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
Response attributes
Table 2. Response attributes and their possible values
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
Example HTTP conversion
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.

Table 3. Operation descriptions for creating metric using POST operation
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

Table 4. Response attributes and their possible values
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.
Example HTTP conversation
Note:
  • 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.
  1. 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
}
  2. 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" 
}
  3. 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.

Table 5. Operation descriptions for updating metric display name using PUT operation
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
Response attribute
Table 6. Response attributes and their possible values
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.
Example HTTP conversion
  1. 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
}
  2. 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"
}
  3. 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"
}
  4. 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.

Table 7. Operation descriptions for creating metric using DELETE operation
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

Table 8. Response attributes and their possible values
Attribute Possible values
error Reason for metric deletion failure

Example HTTP conversation

  1. Metric deleted successfully
    Request
    DELETE
https://localhost:9081/api/sam/v2/metrics?code_name=TEST&token=6b884e39d8d34e05192c5d72dd6739607293b828
    Response
    200 ok
Response body (JSON)
{
}
  2. 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"
}
  3. 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"
}