Retrieving, paginating, filtering and ordering resource details

This section describes how the management API resources are organized, and how to retrieve the current configuration for a resource via the management API. It covers Dealing with resources, Pagination, Filtering and Ordering.

Dealing with resources

Every element on the API is described as a resource.

Using VMRs as an example, VMR configuration is represented by the conference resource. As you typically want to configure more than one VMR, the API lets you deal with multiple resources via a list.

If you do a GET query for api/admin/configuration/v1/conference/ you get all the currently configured VMRs as a list. If you send a DELETE request to the same URL then you will delete all VMR configuration.

However, often you’re only interested in dealing with one VMR, in which case you want the detail of a specific VMR. You can send a GET request with a URL that targets a specific VMR resource, for example a GET of api/admin/configuration/v1/conference/1/ will return only the configuration for the first VMR. Similarly if you want to change just that VMR then you would send a PATCH request to the same URL with just the fields you wanted to change.

Getting a single resource object

By concatenating an object ID with the resource URI, details can be obtained for a single resource object.

For example, to GET the alias with ID 1 the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/1/

The response to a GET for a single resource is a JSON object with attributes for each field of the resource.

The ID of existing objects can be identified from the URI shown in the Administrator interface when viewing the item, for example when viewing a Virtual Meeting Room the URI is in the format https://<manageraddress>/admin/conferencing/conference/117/change/ where in this case the ID of this VMR is 117.

When using the management API to retrieve information about existing resources, the id field identifies the object ID. In this example of a VMR resource, the ID is 3:

Getting multiple resource objects

If a GET operation is invoked on the root resource URI then details about multiple objects are returned. The response to a GET for multiple resources is a JSON object with two attributes:

Attribute Value
meta This is an object giving meta information about the response.
objects This is a list of resource objects.

For example, to GET all conference aliases the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/

Global settings

The global settings (/api/admin/configuration/v1/global/) are a special case.

To make the API as consistent as possible, the global settings are treated in the same way as other resources i.e. there is a list of global settings. However, you are only allowed one global settings resource. Thus, if you get the list of all global settings you will only ever get a list with one entry in it. Also, you are not allowed to delete all global settings.

Therefore you should almost always deal directly with the detail of the existing resource (via api/admin/configuration/v1/global/1/) rather than using it a list.

Pagination

By default, the response is paginated and it contains the first page of 20 results. To retrieve subsequent pages of results the offset parameter must be specified in the URI.

To carry on from our previous example, to retrieve the second page of results the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/?offset=20

The limit parameter can be used to change the number of results in the response.

For example, to return the first 100 objects the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/?limit=100

The limit parameter has a maximum value of 10000.

Note that if there are a large number of aliases configured this may put a significant load on both the Management Node and the client making the request.

Filtering

A request for multiple objects can be filtered so that only those objects that match specific criteria are returned. The table below lists the available match specifiers.

Note that:

  • Filtering is case insensitive for the contains, startswith and endswith keywords (but not exact and regex).
  • The lt , lte, gt and gte filters use ordinal comparison for strings — thus Ark < Rock < ark < rock.
Specifier Description
exact Matches objects whose field exactly matches the value (case sensitive).
iexact Case-insensitive version of the exact match.
contains Matches objects whose field contains the value.
startswith Matches objects whose field starts with the value.
endswith Matches objects whose field ends with the value.
regex Matches objects whose field matches the regular expression value (case sensitive).
iregex Case-insensitive version of the regex match.
lt Matches objects whose field is less than the value.
lte Matches objects whose field is less than or equal to the value.
gt Matches objects whose field is greater than the value.
gte Matches objects whose field is greater than or equal to the value.

The criteria that can be used for filtering are included at the end of the schema for each resource. If no filtering section is present, then filtering is not available.

For example, to see which criteria you can use to filter a search for service aliases, look at the associated schema:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/schema/?format=json

You will see at the end:

filtering: {
    alias: 1,
    conference: 2,
    creation_time": 1,
    description: 1
}

This indicates that you can filter by any of the criteria listed above. The 1 and 2 following each criteria indicate that all of the match specifiers listed in the table above are valid when filtering using that criteria. Alternatively, if not all specifiers are valid, those that are valid are listed instead.

For example, to search for information about the alias meet.alice the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias=meet.alice 

For example, to search for all aliases that start with meet. the URI would be:

https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias__startswith=meet.

To query in an array, for example aliases, you must query on items inside the array i.e. aliases__alias. For example, to display all VMRs containing an alias in a URI format:

https://<manageraddress>/api/admin/configuration/v1/conference/?aliases__alias__contains=@

Ordering

A request for multiple objects can be ordered by field values. For example, to get the conference history ordered by start time the URI would be:

https://<manageraddress>/api/admin/history/v1/conference/?order_by=start_time

The order can be reversed by adding a hyphen character (-) before the field name. For example, to order by descending start time so that the most recent conferences are listed first, the URI would be:

https://<manageraddress>/api/admin/history/v1/conference/?order_by=-start_time

The fields that can be used for ordering are included at the end of the schema for each resource. If an ordering section is not present, then ordering is not available.