Retrieving, paginating, filtering and ordering resource details

This section describes how to retrieve the current configuration for a resource via the management API. It covers Getting a single resource object, Getting multiple resource objects, Pagination, Filtering and Ordering.

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 will be a JSON object with attributes for each field of the resource.

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/

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

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 following match specifiers are available:

Specifier Description
exact Matches objects whose field exactly matches the value.
iexact Case-insensitive version of the exact match.
contains Matches objects whose field contains the value.
icontains Case-insensitive version of the contains match.
startswith Matches objects whose field starts with the value.
istartswith Case-insensitive version of the startswith match.
endswith Matches objects whose field ends with the value.
iendswith Case-insensitive version of the endswith match.
regex Matches objects whose field matches the regular expression value.
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.

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.