This documentation supports the 9.0 version of BMC Atrium Core.

To view the latest version, select the version from the Product version menu.

Operations on instance objects

This section provides the following topics:

Supported operations

The following table explains the HTTP methods used in BMC Atrium Core:

OperationDescriptionURLHTTP methodEquivalent API call
Get an instanceReturns the details of an instance in a particular class./instance/{datasetId}/{namespace}/{className}/{instanceId}GETGetInstance
Get multiple instancesReturns the details of all the instances in a particular class./instance/{datasetId}/{namespace}/{className}GETGetMultipleInstance
Create an instanceCreates new instance in a particular class./instance/{datasetId}/{namespace}/{className}POSTCreateInstance
Modify an instanceUpdates a single instance in a particular class./instance/{datasetId}/{namespace}/{className}/{instanceId}PUTSetInstance
Delete an instanceDeletes an instance in a particular class./instance/{datasetId}/{namespace}/{className}/{instanceId}DELETEDeleteInstance

Common parameters

The following table explains the list of parameters commonly used in the REST operations

NameDescriptionExample
fields

Returns only selected attributes of an instance.

/instance/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/AGGDR4WABLJOBAN1WGQ9AAAE7FEADK?fields=category,token,type
q

Sends a search qualification.

Use a URL-encoded value for the search qualification.

/instance/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?q='dataSet'="BMC.ASSET"

offset

Specifies the number (non-negative integer) of instances to offset the results by. Used for paginating results.

offset=50

Offsets the result by 50 instances

limitSpecifies the number (non-negative integer) of instances to limit the results by. Used for paginating results.

limit=10

Gets no more than 10 instances

sortSorts result on a search by field name and direction. Multiple field names can be used, separated by commas. The direction, is indicated by appending .asc for ascending and .desc for descending after the field name.

sort=Status.asc,Create Date.desc

Sorts first by Status in ascending order and then by Create Date in descending order.

datasetMask

Used to specify the dataset type and to indicate if the overlay behavior of a given dataset should be executed. Based on the datasetId, the instances are retrieved from the given dataset. The dataset can be the current dataset or overlay+original dataset.

/instance/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?datasetMask=0

Value 0 indicates that instance should be searched in underlay dataset if it is not found in the overlay dataset.

Value 1 indicates that instance should be searched in current dataset only.

HTTP status codes

 When responding to requests, the REST API uses some of the HTTP status codes. The following table gives a summary of the different status codes that are returned. Each operation specifies the response code you receive on successful calls or errors.

CodeNameUsage
200OKThis code is the default response for a successful API call. If the documentation does not specify a HTTP status code that is returned on a successful call, it is assumed to be 200.
201CreatedThis code is used when you create new resources. The REST response includes the Link header in the response body which denotes where the new resource is found.
204No ContentThis code is similar to 200, but with no response body. This code is commonly used for DELETE operations.
400Bad RequestThis code is used if the request body is not correct. For example, a JSON document is sent but it is not the correct format or the client sends a date value in the wrong format.
401UnauthorizedThis code is used if the user is not authenticated. 
403ForbiddenThis code is used when the call is authenticated, but the user does not have access to the resource. For example, an entry operation on a class to which the user does not have permission.
404Not foundThis code is used when the specified resource does not exist.
500Internal Server ErrorThis code is the default response for any error that occurs when an API call is being processed.

JSON representation of an error

The HTTP status codes are the response that classify the failure of the request. The HTTP status code is provided in the response header, whereas, the additional information for the error is provided in the response body. The following code sample represents the format of the message you receive when you encounter an error:

[
    {
       "messageType": "ERROR",
       "messageText": "Class does not exist on the server",
       "messageAppendedText": "someClassName",
       "messageNumber": 303
    }
    ...
]
NameData typeDescription
messageTypeStringType of message returned. For example, OK, ERROR, WARNING, FATAL, BAD STATUS.
messageTextStringThe actual text of the error message.
messageAppendedTextStringThe text that augments the error message.
messageNumberIntegerThe error number associated with the error message.

Related topics

Login information

Was this page helpful? Yes No Submitting... Thank you

Comments