REST Auth API: Hypermedia Resources

A key principle of REST is "Hypermedia As The Engine Of Application State". Every resource representation obtained from a REST API request must include URIs that identify that resource and the resources related to it.

The Arlo REST API returns representations comprised of simple properties and Links with URIs to other resources to help you navigate the relationships between resources.

It is possible to navigate and discover the API without reading this documentation at all. Resource endpoint URIs are covered in this documentation for convenience and practical reasons, but since the API is self-describing, the documentation's listing of endpoints is not an essential part of the API design. A reference to the Root collection entrypoint should be sufficient to discover every resource in the API.

Link representation

In XML representations, resource URIs are represented using <Link> elements. These elements can have up to four attributes:

Attribute	Description
rel	Describes the relationship of the referenced resource to the current resource.
type	Describes the media type of the referenced resource and the expected representation that will be returned if the URI is followed.
title	A descriptive name of the referenced resource. The value of this attribute is important when using link expansion.
href	The URI of the referenced resource.

See the remainder of this section for example uses of Links in the REST API.

Self references

Every representation contains a self-referencing URI (i.e. the URI used to retreive it). For example, when you GET an Event instance resource, its URI is included inside a Link reference with a rel value of self:

<Event>
  <EventID>456</EventID>
  <UniqueIdentifier>a34fc9dc-1fa0-9019-b39a-d0fe91119ed6</UniqueIdentifier>
  <Code>MGMT101-001</Code>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/"/>
  ...
</Event>

Collections are also resources, and have a self referencing URI. For example, when you GET a collection of Venues, the self URI of the collection (including any explicit filters or ordering parameters), is included with the resource representation.

<Venues>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Venue" type="application/xml" title="Venue" href="https://demo.arlo.co/api/2012-02-01/auth/resources/venues/847/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Venue" type="application/xml" title="Venue" href="https://demo.arlo.co/api/2012-02-01/auth/resources/venues/848/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Venue" type="application/xml" title="Venue" href="https://demo.arlo.co/api/2012-02-01/auth/resources/venues/849/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Venue" type="application/xml" title="Venue" href="https://demo.arlo.co/api/2012-02-01/auth/resources/venues/850/"/>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/venues/?filter=VenueID%20gt%20846&orderby=VenueID"/>
</Venues>

Resources that have relationships to other resources express these as links with specific rel and title values.

For example, Contact resources may have an associated Address, details of Employment, and a list of Registrations. Each of these associations are represented by a Link element:

<Contact>
  <ContactID>563</ContactID>
  <UniqueIdentifier>af1c9559-a84a-4c60-bcce-7dd98e01fa3f</UniqueIdentifier>
  <FirstName>Sally</FirstName>
  <LastName>Smith</LastName>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/postaladdress/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Employment" type="application/xml" title="Employment" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/employment/"/>
  <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/contacts/563/registrations/"/>
  ...
</Contact>

If an instance end of an association is null or absent (a Contact without a PostalAddress instance, for example), the Link to the resource instance is not included in the representation. Hence it should be assumed that the number and type of Link elements returned may vary between resources. The API will not generate representations that include Links that return HTTP 404 errors if followed. In the example above, if the Contact had no available address or employment information, the PostalAddress and Employment links would be absent from the representation.

When an association is with a resource collection (a collection of Registrations for a Contact, for example), the Link is always included as the collection is never missing, but it may be empty. Clients should not assume that the presence of a Link to a collection resource indicates there are items in that collection.

When parsing resource representations, clients may use the title attribute as a key to identify Links for known relationships. No two Links in a single resource representation share the same title. For example, to get the URI of the Registrations collection for the Contact representation above, an XPath expression can be used:

/Contact/Link[@title='Registrations']/@href

Link expansion

To reduce bandwith requirements, and to better satisfy practical use-cases, the REST API supports inline expansion for most Link elements that reference related resources. Links marked for expansion will eagerly load the referenced resource (which can be a resource instance or a collection) and include it as an 'inline' child of the Link in the response. This allows the retrieval of multiple branches of an object graph in a single HTTP GET. By using expansion, you avoid the process of retrieving a resource and then making additional calls to retrieve details about each linked resource.

To use inline expansion, include the expand query option with the GET request. The syntax of this query option is a comma-separated list of Link titles. Additionally each title can be followed by a forward slash and another title to enable identifying a multi-level relationship. For example ?expand=Employment,Employment/Manager,Employment/Manager/PostalAddress.

This query option uses a silent fail approach to execution, meaning if an expansion expression is not valid, it will be ignored. Resources supporting this feature will list expand as an optional parameter for HTTP GET requests. For resource-specific limitations or restrictions, refer to the reference page for each resource.

For expansions involving resource collections, inlining is limited to the top 100 resources in the collection. Note that filtering, ordering and paging query options are not applied to inlined collections. In scenarios where these limits are too restrictive, the collection should be requested as a separate GET where paging query options can be used in the request to manage the results. Inline link expansion is limited to six nesting levels per request.

Example

GET /api/2012-02-01/auth/resources/contact/563/?expand=Employment,Employment/Organisation

Retrieves information about a Contact resource, including details of their Employment and its associated Organisation.

<Contact>
  <ContactID>563</ContactID>
  <UniqueIdentifier>af1c9559-a84a-4c60-bcce-7dd98e01fa3f</UniqueIdentifier>
  <FirstName>Sally</FirstName>
  <LastName>Smith</LastName>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Employment" type="application/xml" title="Employment" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/employment/">
    <ContactEmployment>
      <Position>Marketing Site Developer</Position>
      <Department>Marketing</Department>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/employment/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/563/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/">
        <Organisation>
          <OrganisationID>823</OrganisationID>
          <Name>Acme Consultants</Name>
          <LegalName>Acme Consultants Limited</LegalName>
          <Email>admin@acme.example.org</Email>
          <CodePrimary>ACMECONSUL04</CodePrimary>
          <CodeSecondary>74-582-821</CodeSecondary>
          <PhonePrimary>+64 4 211 2334</PhonePrimary>
          <PhoneSecondary>+64 4 211 2334 ext 231</PhoneSecondary>
          <WebsiteUrl>acme.example.org</WebsiteUrl>
          <Status>Active</Status>
          <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
          <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
          <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
          <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/postaladdress/"/>
          <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/AccountManager" type="application/xml" title="AccountManager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/32/"/>
          <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
          <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
        </Organisation>
      </Link>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Manager" type="application/xml" title="Manager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/328/"/>
    </ContactEmployment>
  </Link>
</Contact>