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.
Populate
The OfficeRnD API allows you to request related entity information using the $populate method. For example, a visit has an associated visitor (contact information) which you can pull by id and populate the data together with the 'visit' entity. Those objects can be expanded inline with the $populate request parameter.
Objects that can be expanded are noted in this documentation. This parameter is available on all GET API requests.
Important
Populating queries only work for requests made to the whole collection, e.g. /members and not when calling a specific id in that collection, i.e. /members/member-id.
Example 1 - the filter below will expand the "office" parameter into an object, where apart from the _id of the location with which the membeis associated you'll also find the actual name of the location.
/members?$populate=office.name
Example 2 - the filter below will expand the "createdBy" and "modifiedBy" parameters so that the name of the user who performed the respective action is visible, rather than just the user _id:
?$populate=modifiedBy.name,createdBy.name
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.
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.
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.
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
Important
Objects that can be expanded are noted in this documentation.
Updated 2 months ago