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/bridge/vlans
/system/users
/fullconfigs

A GET request to a collection returns a list of the URIs of the members of the collection. The following example shows the GET request and returned response for the vlans collection:

$ curl GET -k -b /tmp/auth_cookie "https://192.0.2.5/rest/v1/system/bridge/vlans"
[
  "/rest/v1/system/bridge/vlans/1",
  "/rest/v1/system/bridge/vlans/10",
  "/rest/v1/system/bridge/vlans/20"
]

The brackets ([and ]) enclose the list. 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/v1/system/bridge/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 the bridge resource:
```
/system/bridge/vlans
```
In the following example, routes is a subcollection of the default 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/bridge
/system/mclag
/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 GET -k -b /tmp/auth_cookie "https://192.0.2.5/rest/v1/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"
}