General principles for using the REST API

This topic describes the principles common to the endpoints provided by the BMC Network Automation REST API.

HTTP verbs

Where possible, endpoints use the following verbs consistently:

Input encoding

When constructing the URL for an endpoint that contains a dynamic portion (either in the path or in the query string), ensure you correctly encode characters that are not permitted in a URL. For example:

https://serverName:portNumber/bca-networks/api/v2.0/groups?filter.realm=my%20realm%20name

An encoding reference is available here.

Similarly, if you are editing JavaScript Object Notation (JSON) request bodies by hand, you must escape any reserved characters in your strings.

Note that you cannot include names or values containing forward slash or backslash in the URL (such as getting a component by a name that contains a slash, or filtering by a value that contains a slash). The BMC Network Automation web server always considers slashes to be path delimiters and that behavior cannot be escaped, not even by using URL encoding. Such a URL returns an HTML error page reporting an invalid URL.

JSON

JSON is used for both request and response bodies. For JSON syntax basics, see http://www.json.org/.

To summarize JSON syntax, an object is a collection of comma-separated name/value pairs enclosed by curly braces; names are enclosed in double quotes. The name/value pairs are not ordered. Sometimes a value is an ordered list or array of values or contained objects, which are enclosed by square brackets.

Request and response bodies that carry JSON are carrying representations of the object model being exchanged. Most of the objects are named ending in DTO, meaning "data transfer object." These object names appear in the Swagger UI and in the Object Definitions section. An object definition uses curly braces to indicate an object contains a collection of the indicated attributes; and uses square brackets to indicate a value is made up of a comma-separated ordered list or array of values. The object definitions documentation provides the following information about each attribute:

attribute_name : attribute_type *
description

Or, for an array type of attribute:

attribute_name : [
    description
    attribute_type
] *

Or, for a map type of attribute:

attribute_name : {
    description
} *

For example, if the object definition looks like this:

 {
    id: string
    The unique database key (read-only)
 
    name: string*
    The unique name

    severityIds: [
        One or more event severities.
        integer
    ]

    runtimeProperties : {
        Name/value pairs for runtime parameters; this is a map where the key is the property name string and the value is the property value string
    }
 }

Then the object built from this definition might look like this (where white space outside of quoted strings is not significant):

{
    "id" : "123456-1",
    "name" : "some component name",
    "severity": [
        1, 2, 3
    ],
    runtimeProperties : {
        "pingAddress" : "1.2.3.4",
        "pingCount" : "5",
        "pingTimeout" : "15"
    }
}

Attribute naming conventions

Attributes are named such that you can recognize them when you look at the same component in the GUI. Any attribute name ending in Id, Ids, Guid, or Guids contains some sort of identifying value, either a database key specific to the server, a numeric value with a specific meaning, or a GUID of a device adapter. The ID can be used to look up the referenced component by the database key, or the ID or GUID can be found via the value mapping services.

ComponentId attributes and portability

When one component refers to another component, the JSON attribute value for the referenced component contains a representation of the ComponentId object. A ComponentId carries the database key of the component, which is specific to one particular BMC Network Automation server, the component's name and type, and any additional information needed to identify the component uniquely. The name and type are portable across different servers. When you GET a component, the ComponentId is fully populated to identify the component uniquely. If you then pass in this same ComponentId in a POST or a PUT request, the system uses the information provided to lookup the component and to verify what is found. The database key need not be present and it need not look up successfully. Thus a component can be exported from one server using a GET and imported into another server using a POST, and the resulting component and its references turn out the same in both the systems.

For example, a rule set refers to an assigned network span that is a group. When you GET the rule set, it includes a ComponentId for the group, containing the database key, name, type, and realm of the group. If you want to add this same rule set into a different system, you can send it the same JSON string that your GET request returned. The new rule set will be associated with the same group, so long as the group exists under the same name and in the same realm.

The following is an example of a ComponentId in JSON format that refers to a group. This example is fully populated, but you can leave out the id (so long as you fill in the componentName and qualifiers), or you can leave out the componentName and qualifiers (so long as you fill in the id). The qualifiers vary by componentType; see the complete ComponentId documentation.

{
    "id": "1415436101-46",
    "componentName": "DeviceType.Cisco IOS Switch/Router",
    "componentType": "Group",
    "qualifiers": {
        "realmName": "Default"
    }
}

The discriminator attribute

Some objects have a complex inheritance graph, similar to what is typically used in any object-oriented programming language. For example, in the jobs and predefined jobs areas, the ActionDTO class holds the attributes common to all actions; it is the root of the action class hierarchy. By itself, it does nothing, since it does not hold the attributes specific to a particular action. That is, it is missing the attributes to perform a snapshot or a reboot. It is actually the subclasses of ActionDTO that appear in the JSON strings, and each subclass carries a required attribute known as a discriminator. This attribute tells both the client and the server which concrete subclass is being represented. The discriminator attribute used by BMC Network Automation is always named @class and its value is the full name of the subclass. The full subclass names are shown in the Object Definitions section for the concrete subclasses.

For example, a snapshot action JSON string within a job in a request body might look like the following, where it holds attributes from SnapshotActionDTO, its immediate parent class SpanActionDTO, and the root class ActionDTO:

{
    "@class":"com.bmc.bcan.rest.services.v2_0.ActionService$SnapshotActionDTO",
    "annotation":"nightly backup",
    "useAuxiliaryInterfaceFlag":false,
    "spanParams": {
        "spanIds": [
            {
                "componentName": "Default",
                "componentType": "Realm"
            }
        ]
    },
    "markAsTrustedFlag":true
}

Timestamps

You can provide input dates in the RFC-1123, ISO-8601 format. Also, REST API recognizes numeric (integer) serializations assumed to be in the Unix timestamp notation (milliseconds since epoch, Jan 1st 1970 00:00:00 GMT).

All timestamps in response bodies are returned in the ISO 8601 format and are in the server time zone.

YYYY-MM-DDTHH:MM:SS+HH:MM

Passwords

When the value of an attribute in a JSON string is a password, that password is in clear text. Therefore the client script or program is responsible for protecting any such password it might send to or receive from the server. Note that the use of HTTPS protects the password over the connection between the client and the server.

Pagination

Several endpoints have the potential to return large amounts of data in their responses. These endpoints support a common approach for returning paginated results, defaulting to the first 25 results. Use the limit request parameter to specify how many results make up one page and thus how many results should be returned. Use the offset request parameter to specify which page should be returned.

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 5108184138865664178' 'https://serverName:portNumber/bca-networks/apidocs/v2.0/devices?limit=25&offset=1'

Here, the limit parameter indicates the maximum number of items displayed on one page in the result. The offset parameter indicates the page number. 

A paginated response includes a Total-Count in the response header. This count indicates how many results are available in total, which can aid you in asking for more pages, if, for example, you are implementing some sort of user-driven paged list display.

Error responses

Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. In some cases, the response body might also contain an object holding details of the error, with the following fields:

Here is an example request, resulting in the response 500 Internal Server Error:

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer -2271976100240036894' 'https://serverName:portNumber/bca-networks/api/v2.0/realms'
 
500 Internal Server Error: Unexpected error occurred: IllegalArgumentException: Index smaller than zero is not allowed

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid leaking information to the caller.

Unsupported features

You cannot perform the following tasks by using the REST API:

• You cannot retrieve or edit group ACLs.
• You cannot retrieve or edit rule set ACLs.
• You cannot retrieve template ACLs.
• While deploying an OS image, you cannot specify the OS binary image file to load from your local disk.
• You cannot create or edit a Compliance Status action in a job or predefined job. The compliance information is available via devices and their detailed status.
• You cannot create or edit a Telnet/SSH Session action in a job.