Resource collections and singletons
Collections
A collection is a directory of resources managed by the server. Typically, a resource collection contains multiple resource instances and the collection name is in the plural form.
For example:
/system/vlans
/system/users
/fullconfigs
A GET request to a collection returns the set of JSON objects representing the members of the collection. The following example shows the GET request and returned response for the
vlans
collection:
$ curl -k GET -b /tmp/auth_cookie "https://192.0.2.5/rest/v10.04/system/vlans" { "1": "/rest/v10.04/system/vlans/1", "10": "/rest/v10.04/system/vlans/10", "20": "/rest/v10.04/system/vlans/20" }
Each URI in the list represents a configured VLAN.
To get the JSON data for VLAN 10, you must either send the GET request to the URI representing VLAN 10 ("/rest/v10.04/system/vlans/10"
), or you must use the depth parameter to expand the list of URIs in the
vlans
collection to get the JSON data for all the VLANs in the collection.
Subcollections
A single resource instance can also contain subcollections of resources.
In the following example,
vlans
is a subcollection of thesystem
resource:/system/vlans
In the following example,
routes
is a subcollection of thedefault
VRF resource instance:/system/vrfs/default/routes
Singletons
There are some resources that can only have one instance. These resources are called singletons and the resource collection name is in the singular form.
For example:
/system
/system/vsx
/firmware
Because there is only one resource in a singleton collection, GET requests return the JSON representation of the resource instead of a URI list of one item. In addition, you do not need to supply a resource ID in the URL of a GET request. For example, a GET request to the firmware URI returns the JSON data that represents the firmware resource:
$ curl -k GET -b /tmp/auth_cookie "https://192.0.2.5/rest/v10.04/firmware"
{
"current_version": "TL.10.00.0006E-686-g4a43ab9",
"primary_version": "TL.10.00.0006E-686-g4a43ab9",
"secondary_version": "",
"default_image": "primary",
"booted_image": "primary"
}