Getting information about a resource definition

You can obtain information about a resource definition. If the requested resource definition does not exist, then an error message is received in a response message. You can request information for multiple resource definitions in a single request.

Request line

baseURL/dbapi.do?action=retrieveResourceDef&dataset=<Datasetname>

Request body

{
  "types":[
    "",
    "",
    ""
  ]
}

Request example using GET

GET /dbapi.do?action=retrieveResourceDef&dataset=defaultDs&types=host,vm,disk HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk

Request example using POST

POST /dbapi.do?action=retrieveResourceDef&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk

{
  "types":[
    "host",
    "vm",
    "disk"
  ]
}

Request parameters

Parameter	Type	Description
action	String	retrieveResourceDef Specify the API function to be invoked.
dataset	String	Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed.
types	String[ ]	(Optional) One or more comma-separated resource types. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. Default: Retrieves all resource definitions.

Parameter

Type

Description

action

String

retrieveResourceDef

Specify the API function to be invoked.

dataset

String

Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed.

types

String[ ]

(Optional) One or more comma-separated resource types.

From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed.

Default: Retrieves all resource definitions.

Response body

{
  "retrieved":[
    {
      "type":"",
      "name":"",
      "attributes":[
        "",
        "",
        ""
      ],
      "relations":[
        ""
      ]
    }
  ],
  "failed":[
    {
      "code":"",
      "type":"",
      "error":""
    }
  ]
}

Response example

{
  "retrieved":[
    {
      "type":"host",
      "name":"Host",
      "attributes":[
        "name",
        "cpuUsage",
        "memUsage"
      ],
      "relations":[
        "disk"
      ]
    }
  ],
  "failed":[
    {
      "code":"32040005",
      "type":"disk",
      "error":"Resource definition with {type}:[disk] does not exist"
    },
    {
      "code":"32040005",
      "type":"vm",
      "error":"Resource definition with {type}:[vm] does not exist"
    }
  ]
}

Response parameters

Parameter	Type	Description
retrieved	Object[ ]	List of resource definitions.
retrieved.type	String	Resource type.
retrieved.name	String	Resource definition name.
retrieved.attributes	String[ ]	List of scalar and timeseries attribute IDs.
retrieved.relations	String[ ]	List of related resource types.
retrieved.additionalProperties	Object	All defined additional properties.
failed	Object[ ]	List of failed entities.
failed:code	String	Eight-digit hexadecimal error code.
failed:type	String	Failed resource type.
failed:error	String	Error message.

Status codes

Status code	Message	Description
200	OK	Request was successful, and the response body contains the requested log details.
206	PARTIAL CONTENT	Request is in progress, and the incremental content is available in the response body.
277	PARTIAL OK	Request completed successfully with some failures. Check the response body for details.
400	BAD REQUEST	Request URL or request body validation failed. Check the response body for details.
401	UNAUTHORIZED	Supplied authentication token is invalid or does not have the appropriate credentials to access the resource.
404	NOT FOUND	API server could not find a resource matching the request.
405	METHOD NOT ALLOWED	Request HTTP method is not allowed for the operation.
500	SERVER ERROR	API operation request failed. Check the response body for details.

Note: If all of the specified resource definitions fail, then the 500 SERVER ERROR message is received in the response message.

Response codes

The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.

Response code	Message	Condition
32040005	Resource definition with {type}:[host] does not exist.	Minimum of one resource definition is obtained and getting one or more resource definition types failed. Specified resource definition type does not exist.
3202000F	Invalid value specified for parameter {type}. Resource {type}:[!] contains invalid characters. Valid characters are [alphanumeric, - and _].	Minimum of one resource definition is obtained and getting one or more resource definition types failed. Specified resource type contains invalid characters.
32040008	Mandatory parameter {type} not specified.	Minimum of one resource definition is obtained and getting one or more resource definition types failed. Specified resource type is blank.
3202000F	Invalid value specified for parameter {type}. Resource {type}:[IAmSuchABigStringWhichIsNotAllowedAsResourceTypeInMARSBM] length must be between 1-32 characters.	Minimum of one resource definition is obtained and getting one or more resource definition types failed. Specified resource type is not valid in terms of allowed length.
32010002	Invalid JSON Request.	Specified JSON input is invalid.
320000E9	License is not valid.	License is not uploaded, or the uploaded license is invalid or expired.
320000E9	Authorization needed.	Request is sent with an invalid authentication token.
320000E4	Dataset with {name}:[ds1] does not exist .	Request is sent for a dataset that does not exist.
320000E0	HTTP method [PUT] is not supported for action [retrieveResourceDef.]	Request is sent with any HTTP method other than POST.
320000E2	Application encountered an internal error.	API server encountered an unknown error.