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 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/vlans"
[
  "/rest/v1/system/vlans/1",
  "/rest/v1/system/vlans/10",
  "/rest/v1/system/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/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.

An exception to the bracket format is the response for certificates. For certificates, braces enclose the list and index information is provided. For example:

$ curl GET -k -b /tmp/auth_cookie "https://192.0.2.5/rest/v1/certificates"
{
  "my-cert-1": "/rest/v1/system/certificates/my-cert-1",
  "my-cert-2": "/rest/v1/system/certificates/my-cert-2"
}

Subcollections

A single resource instance can also contain subcollections of resources.

In the following example, vlans is a subcollection of the system resource:
```
/system/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/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 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"
}