Arlo

REST Auth API: Collection Resources

All of the major resources in the REST API have a 'master' collection which is the primary mechanism for discovering, filtering, and updating any instance of those resources. All of the these collections are children of a single root collection which defines the entrypoint for the entire REST API. This root collection is located at:

/api/2012-02-01/auth/resources/

Accessing this resource will return a list with links to all of the major resource collections in the API, such as the Events, Contacts, and Registration collections.

Any queries or filters on the REST API are executed against collection resources, so understanding how they are represented and what options are available is important. This section covers how to use collections, and how to apply query options to achieve paging and filtering of responses.

General response format

Collections are represented as a list of Link elements inside a toplevel root element.

For example, the Events collection is represented in XML as:

GET /api/2012-02-01/auth/resources/events/

<Events>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/3/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/4/"/>
  ...
  <Link rel="next" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/?skip=100"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/"/>
</Events>

In addition to Link elements for collection items, the collection representation always includes a self link, and an optional next link (see paging).

Link expansion

Collection resources support link expansion which can be used to inline representations of resources within the collection response. For example, when accessing the Events collection, including the ?expand=Event query option will cause the collection response to expand to include Event representations:

GET /api/2012-02-01/auth/resources/events/?expand=Event

<Events>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/">
    <Event>
      <EventID>1</EventID>
      <UniqueIdentifier>a34fc9dc-1fa0-9019-b39a-d0fe91119ed6</UniqueIdentifier>
      <Code>MGMT101-001</Code>
      <StartDateTime>2012-02-02T09:00:00.000+12:00</StartDateTime>
      <FinishDateTime>2012-02-03T17:00:00.000+12:00</FinishDateTime>
      <StartTimeZoneAbbr>NZDT</StartTimeZoneAbbr>
      <FinishTimeZoneAbbr>NZDT</FinishTimeZoneAbbr>
      <Description>2 days, 9:00AM - 5:00PM</Description>
      <LocationName>Wellington</LocationName>
      <Status>Completed</Status>
      <CreatedDateTime>2012-01-01T04:28:00.5Z</CreatedDateTime>
      <LastModifiedDateTime>2012-01-01T09:25:05.703Z</LastModifiedDateTime>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/EventTemplate" type="application/xml" title="EventTemplate" href="https://demo.arlo.co/api/2012-02-01/auth/resources/eventtemplates/123/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Logistics" type="application/xml" title="Logistics" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/logistics/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Sessions" type="application/xml" title="Sessions" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/sessions/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/RegistrationSettings" type="application/xml" title="RegistrationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/registrationsettings/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Registrations" type="application/xml" title="Registrations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/registrations/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationSettings" type="application/xml" title="PublicationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/publicationsettings/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationStatus" type="application/xml" title="PublicationStatus" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/1/publicationstatus/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/TimeZone" type="application/xml" title="TimeZone" href="https://demo.arlo.co/api/2012-02-01/auth/resources/timezones/1/"/>
      <Link rel="related" type="text/html" title="WebsiteRegister" href="http://www.example.org/register?sgid=a34fc9dc-1fa0-9019-b39a-d0fe91119ed6"/>
    </Event>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Event" type="application/xml" title="Event" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/">
    <Event>
      <EventID>2</EventID>
      <UniqueIdentifier>facfc811-1fa0-9019-b39a-d0fe91119ed6</UniqueIdentifier>
      <Code>MGMT101-002</Code>
      <StartDateTime>2013-02-02T09:45:00+12:00</StartDateTime>
      <FinishDateTime>2013-02-02T11:15:00+12:00</FinishDateTime>
      <StartTimeZoneAbbr>NZDT</StartTimeZoneAbbr>
      <FinishTimeZoneAbbr>NZDT</FinishTimeZoneAbbr>
      <LocationName>Wellington</LocationName>
      <Status>Active</Status>
      <CreatedDateTime>2012-01-01T04:28:00.5Z</CreatedDateTime>
      <LastModifiedDateTime>2012-01-01T09:25:05.703Z</LastModifiedDateTime>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/EventTemplate" type="application/xml" title="EventTemplate" href="https://demo.arlo.co/api/2012-02-01/auth/resources/eventtemplates/123/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Logistics" type="application/xml" title="Logistics" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/logistics/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Sessions" type="application/xml" title="Sessions" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/sessions/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/RegistrationSettings" type="application/xml" title="RegistrationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/registrationsettings/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Registrations" type="application/xml" title="Registrations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/registrations/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationSettings" type="application/xml" title="PublicationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/publicationsettings/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationStatus" type="application/xml" title="PublicationStatus" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/2/publicationstatus/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/TimeZone" type="application/xml" title="TimeZone" href="https://demo.arlo.co/api/2012-02-01/auth/resources/timezones/1/"/>
      <Link rel="related" type="text/html" title="WebsiteRegister" href="http://www.example.org/register?sgid=facfc811-1fa0-9019-b39a-d0fe91119ed6"/>
    </Event>
  </Link>
  ...
  <Link rel="next" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/?expand=Event&skip=100"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/?expand=Event"/>
</Events>

As with instance resources, the expand query option can be used with multi-level expansion expressions to recursively inline resources. For example, to inline Events and their associated TimeZone and EventTemplate resources, the request can be modified to:

GET /api/2012-02-01/auth/resources/events/?expand=Event,Event/TimeZone,Event/EventTemplate

This query option allows for up to six levels of expansion.

Filtering

Collections support the use of filter expressions to return only a subset resources matching specific criteria. Filter expressions can be specified using the filter query option. The filtering grammar for this feature is based on the OData filter URI protocol.

For example, to filter the Contact collection and return only individuals with an associated PostalAddress with a City value of Auckland, a filter can be used:

GET /api/2012-02-01/auth/resources/contacts/?filter=PostalAddress/City eq 'Auckland'

Filter syntax

The filter expression language supports the following operators:

Operator Description Example
Logical Operators
Eq Equal [...]/resources/contacts/?filter=PostalAddress/City eq 'Auckland'
Ne Not equal [...]/resources/contacts/?filter=PostalAddress/City ne 'Wellington'
Gt Greater than [...]/resources/venuerooms/?filter=Capacity gt 20
Ge Greater than or equal [...]/resources/venuerooms/?filter=Capacity ge 40
Lt Less than [...]/resources/venuerooms/?filter=Capacity lt 10
Le Less than or equal [...]/resources/venuerooms/?filter=Capacity le 10
And Logical and [...]/resources/contacts/?filter=PostalAddress/City eq 'Auckland' and Status eq 'Active'
Or Logical or [...]/resources/contacts/?filter=PostalAddress/City eq 'Auckland' or PostalAddress/City eq 'Wellington'
Not Logical negation [...]/resources/contacts/?filter=not endswith(Email,'.com.au')
Arithmetic Operators
Add Addition [...]/resources/venuerooms/?filter=Capacity add 5 gt 10
Sub Subtraction [...]/resources/venuerooms/?filter=Capacity sub 5 gt 10
Mul Multiplication [...]/resources/venuerooms/?filter=Capacity mul 2 gt 100
Div Division [...]/resources/venuerooms/?filter=Capacity div 2 gt 10
Mod Modulo [...]/resources/venuerooms/?filter=Capacity mod 2 eq 0
Grouping Operators
( ) Precedence grouping [...]/resources/venuerooms/?filter=(Capacity sub 2) gt 10

In addition to operators, a set of functions are also defined for use with the filter query option. The following table lists the available functions.

Function Example
String Functions
bool substringof(string po, string p1) [...]/resources/organisations/?filter=substringof(Name, 'Limited') eq true
bool endswith(string p0, string p1) [...]/resources/contacts/?filter=endswith(Email, '.co.nz') eq true
bool startswith(string p0, string p1) [...]/resources/eventtemplates/?filter=startswith(Code, 'MGMT') eq true
int length(string p0) [...]/resources/organisations/?filter=length(Name) gt 50
int indexof(string p0, string p1) [...]/resources/organisations/?filter=indexof(Name, 'Ltd') gt 0
string replace(string p0, string find, string replace) [...]/resources/organisations/?filter=replace(Name, ' ', '') eq 'AcmeLimited'
string substring(string p0, int pos) [...]/resources/organisations/?filter=substring(Name, 2) eq 'me Limited'
string substring(string p0, int pos, int length) [...]/resources/organisations/?filter=substring(Name, 2, 8) eq 'me Limit'
string tolower(string p0) [...]/resources/organisations/?filter=tolower(Name) eq 'acme limited'
string toupper(string p0) [...]/resources/organisations/?filter=toupper(Name) eq 'ACME LIMITED'
string trim(string p0) [...]/resources/organisations/?filter=trim(Name) eq 'Acme Limited'
string concat(string p0, string p1) [...]/resources/organisations/?filter=concat(concat(PostalAddress/City, ', '), PostalAddress/Country) eq 'Wellington, New Zealand'
Date Functions
int day(DateTime p0) [...]/resources/organisations/?filter=day(datetime(CreatedDateTime)) eq 2
int hour(DateTime p0) [...]/resources/organisations/?filter=hour(datetime(CreatedDateTime)) eq 0
int minute(DateTime p0) [...]/resources/organisations/?filter=minute(datetime(CreatedDateTime)) eq 30
int month(DateTime p0) [...]/resources/organisations/?filter=month(datetime(CreatedDateTime)) eq 12
int second(DateTime p0) [...]/resources/organisations/?filter=second(datetime(CreatedDateTime)) eq 0
int year(DateTime p0) [...]/resources/organisations/?filter=year(datetime(CreatedDateTime)) eq 2010
Math Functions
double round(double p0)
decimal round(decimal p0)
double floor(double p0)
decimal floor(decimal p0)
double ceiling(double p0)
decimal ceiling(decimal p0)

Examples

Example 1

Filter expression to retrieve a collection of all Contacts who have registered for an Event in the past week (since 1 Feb 2012 12:00AM UTC)

GET /api/2012-02-01/auth/resources/registrations/?filter=CreatedDateTime gt datetime('2012-02-01T00:00:00.000Z')&expand=Contact

Note the request includes an expansion of the Contact link for each Registration.

Example 2

Filter expression to retrieve a collection of all EventSessions starting in the next week (starting before 7 Mar 2012 12:00AM UTC) that will be presented by John Mitchell (with ContactID 7732)

GET /api/2012-02-01/auth/resources/eventsessions/?filter=Presenter/ContactID eq 7732 and Status eq 'Active' and StartDateTime lt datetimeoffset('2012-03-07T00:00:00.000Z')

Example 3

Filter expression to retrieve a collection of all Contact resources created or modified after a specific DateTime (1 Jan 2001 12:00AM UTC)

GET /api/2012-02-01/auth/resources/contacts/?filter=LastModifiedDateTime gt datetime('2001-01-01T00:00:00.000Z') or CreatedDateTime gt datetime('2001-01-01T00:00:00.000Z')

Example 4

Filter expression to search a collection of all EventSession resources for one with a specific UniqueIdentifier

GET /api/2012-02-01/auth/resources/eventsessions?filter=UniqueIdentifier eq guid('e8d3e436-765d-4e45-8c69-491ec8113482')

Sorting

Collections support the use of sorting expressions to return the requested resources in a specified order. Sort expressions can be specified using the orderby query option. The grammar for this feature is based on OData URI conventions.

For example, to order the contents of the Contact collection by LastName, the following request can be used:

GET /api/2012-02-01/auth/resources/contacts/?orderby=LastName

To reverse the ordering, the desc keyword can be used:

GET /api/2012-02-01/auth/resources/contacts/?orderby=LastName desc

Secondary sorts can also be specified with the same syntax:

GET /api/2012-02-01/auth/resources/contacts/?orderby=LastName, FirstName

Paging

Query options

Collection resources support two query options to support paging.

Parameter Description
skip Returns a subset of records from the collection, starting at index N+1 specified by this parameter.
top Returns a subset of records from the collection, starting at index 0 or index skip, and returns the first N records. If unspecified, a default of 100 is used. The maximum supported value is 250.

By default, all collections are limited to 100 resources per request.

Examples

Retrieve the top 20 resources from the Event collection:

GET /api/2012-02-01/auth/resources/events/?top=20

Using a page size of 10, retrieve resources on page 4 from the Event collection:

GET /api/2012-02-01/auth/resources/events/?skip=30&top=10

Next link

When more resources are available (meaning more pages of results exist), the REST API will include a Link element in the collection with a rel attribute value of next. The URI for the link includes all existing parameters (including filters), and increments the skip parameter so the next request starts with the first entity of the next page.

For example:

GET /api/2012-02-01/auth/resources/contacts/?filter=PostalAddress/City eq 'Wellington'&top=5

<Contacts>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/4/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/6/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/8/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/9/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/10/"/>
  <Link rel="next" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/?filter=PostalAddress%2FCity%20eq%20'Wellington'&skip=5&top=5"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/?filter=PostalAddress%2FCity%20eq%20'Wellington'&top=5"/>
</Contacts>

The collection includes a next link with a skip of 5, and includes the original filter details.