Resource collections and singletons


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 ""

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.


A single resource instance can also contain subcollections of resources.

  • In the following example, vlans is a subcollection of the bridge resource:

  • In the following example, routes is a subcollection of the default VRF resource instance:



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 ""
  "current_version": "TL.10.00.0006E-686-g4a43ab9",
  "primary_version": "TL.10.00.0006E-686-g4a43ab9",
  "secondary_version": "",
  "default_image": "primary",
  "booted_image": "primary"