Querying data
Please, note that as OfficeRnD is evolving as the leading Flexible Workspace Management Platform, we're doing our best to document all available system entities and their properties that we believe are important for external usage.
We explicitly may not document some properties that we believe should be used only internally. We will strongly recommend that you don't use fields that are not documented here as we might change them in the future. We can guarantee future API compatibility only for documented entities and their properties.
Paging
OfficeRnD API allows you to pass paging parameters in order to correctly traverse through a high number of results.
In order to tranvere through the results of a listing API, you need to use the $limit
, $next
or $prev
query parameters. If successsful, the response will return a list of only limited number of results and additional metadata in headers.
The $limit parameter
In order to limit the number of results returned you can use to $limit
query parameter and pass a number.
Important
Please note that if an endpoint has the $limit parameter mentioned in the documentation, then it is mandatory for said endpoint.
The default limit is 100 and it cannot be exceeded.
Failing to specify a limit when calling an endpoint will result in the application of the default limit.
Example: You've a 1000 members that you'd like to call, but don't specify that you only want to get the first 50 by using $limit=50 and you call just /members.
The response body will contain 100 members, as if $limit was set to 100.
The endpoints for which the $limit parameter applies are:
Example
The example below will return only 10 items from the list of results.
$limit=10
The $next parameter
To successfully traverse a list of results, you need use the $limit
parameter in combination with the $next
parameter. While $limit
reduces the number of returned results, the $next
parameter points to the start of the current page. If $next
parameter is not passed, the first page is assumed.
Example
The example below will return 10 items from the list of results at next page with pointer "eyJrIjoibmFtZSIsInYiOiJTYW1wbGUiLCJwIjoyMCwiX2lkIjoiNWE3YTE2MDQwMGExNjA0MDAwYThjMzcifQ=="
$limit=10&$next=eyJrIjoibmFtZSIsInYiOiJTYW1wbGUiLCJwIjoyMCwiX2lkIjoiNWE3YTE2MDQwMGExNjA0MDAwYThjMzcifQ==
The $prev parameter
The $prev
parameter is an alternative to the $next
parameter and can be used when moving through the results pages backwords. In other words, if you need to go to the previous results page rather than the next one. You need use the $limit
parameter in combination with the $prev
parameter.
Example
The example below will return 10 items from the list of results at previous page with pointer "eyJrIjoibmFtZSIsInYiOiJTYW1wbGUiLCJwIjoyMCwiX2lkIjoiNWE3YTE2MDQwMGExNjA0MDAwYThjMzcifQ=="
$limit=10&$prev=eyJrIjoibmFtZSIsInYiOiJTYW1wbGUiLCJwIjoyMCwiX2lkIjoiNWE3YTE2MDQwMGExNjA0MDAwYThjMzcifQ==
Note
If both
$next
and$prev
are passed to the request$next
pointer takes precedence.
Response headers
Each request which contains the $limit
and $next
or $prev
parameters will return additional headers in the response with metadata regarding the request.
rnd-cursor-next
- a cursor pointer to the next page. The value of this header should be passed as$next
query parameter. If there is no next page this header will not be returned.rnd-cursor-prev
- a cursor pointer to the previous page. The value of this header should be passed as$prev
query parameter. If there is no previous page this header will not be returned.rnd-range-start
- the numeric index of the first returned item. If the full list consists of 300 items and you iterate over all items using a$limit
of 10, on the second page you will get items with numeric index 11 to 20.rnd-range-start
will be 11.rnd-range-end
- the numeric index of the last returned item. If the full list consists of 300 items and you iterate over all items using a$limit
of 10, on the second page you will get items with numeric index 11 to 20.rnd-range-end
will be 20.
Note
Objects which have paging enabled are noted in this documentation.
Select
Sometimes you may not need all the fields of a given object. You can optimize your queries by passing the $select request parameter to filter only the fields you need.
This parameter is available to all GET requests. This option works for both object lists or single object requests.
Example - the filter below will return an array of all members, containing only their names and _ids.
/members?$select=name
Filter
You can filter the results of get requests by adding query parameters. For example, if you want to find all members which are part of a company you can add team= in the query string.
You can use wildcard matches on some string fields if you want to find a group of entities. Use $sw, $ew, $cs for starts with, ends with and contains matches. If you need to perform a case insensitive search, just use $swi, $ewi and $csi.
Example 1 - if you want to find all members with a name starting with "john" no matter the case you can pass
/members?name.$swi=john
Example 2 - you can get all invoices for a specific period with a date filter
/payments?date.$gte=2022-06-01T00:00:00.000Z&date.$lte=2022-07-01T23:59:59.999Z
Important
Please, note that as these are query parameters their values need to be URL encoded.
Sorting
OfficeRnD API allows you to pass sorting description using the $sort
query parameter. For example, you may want to list all members and sort them by name. This result can be achieved using the $sort
request parameter. The value of this parameter needs to be comprized by the name of the field you want to sort by, followed by a colon and the sorting direction (asc
for ascending desc
for descending). If you want to request a list to be sorted by the name property ascending you need to pass - $sort=name:asc
.
Updated 8 months ago