REST Auth API: IntegrationData

IntegrationData is a useful mechanism for integrators to use when they need to persist state information at Arlo's end. State information is isolated by vendor (to avoid conflicts).

IntegrationData persistence is supported for Contact and Organisation resources. The content in this article is relevant to both types of resources, though for brevity many examples use only contact references.

Typically the information stored consists of reference codes for the entity in an external system, boolean flags about whether an entity is excluded from integration, or the time of the last sync attempt.

The number and type of values stored are proprietary to the vendor, and are opaque to Arlo. Values are treated as strings.

The integration data is represented by two structures:

A collection structure containing links to all vendors that have integration data stored against the entity.
A name-value map structure containing persisted data for each vendor.

This resource supports retrieval of instance integration data for a specific vendor, a collection of integration data for all vendors, and adding or updating vendor data.

IntegrationData instance resource

Resource URI

/api/2012-02-01/auth/resources/{ResourceType}/{ResourceID}/integrationdata/{VendorID}/

Examples

URI vendor AcmeLtd's data for a Contact:
/api/2012-02-01/auth/resources/contacts/99372/integrationdata/acmeltd/
URI vendor AcmeLtd's data for an Organisation:
/api/2012-02-01/auth/resources/organisations/3264/integrationdata/acmeltd/

General structure

The structure in this example is for ContactIntegrationData, and contains data stored by vendor AcmeLtd containing five settings.

<ContactIntegrationData>
  <VendorID>AcmeLtd</VendorID>
  <SuppressIntegration>true</Alpha>
  <Uri>https://app.acmeltd.org/contacts/9943lkz0ll104/edit</Uri>
  <ID>9943lkz0ll104</ID>
  <Alpha>true</Alpha>
  <Beta>992300</Beta>
  <Gamma>john.smith@example.org</Gamma>
  <Epsilon>2012-01-01T19:02:01+0100</Epsilon>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/salesforce/"/>
</ContactIntegrationData>

Known resource properties

While structure supports arbitrarily-named elements, there are a number of known properties understood by Arlo. If specified, Arlo will use these in its UI to allow easy linking to an external system.

Property	Description
VendorID	A string value identifying the vendor, up to 64 characters long.
SuppressIntegration	A boolean value indicating whether integration is enabled for the entity. NOTE: This is an external flag only and will not have any functional effect regarding how Arlo handles the entity. This flag is designed for UI purposes only so that Arlo can indicate to an administrator that integration with a vendor's system is disabled for that contact. It is the responsibility of the vendor's integration code to honor the value of this flag if it is set.
Uri	A string representing an external URI reference for the entity in an external system, up to 128 characters long. If provided, Arlo may use this URI to provide a useful hyperlink for administrators when editing a contact.

`ContactIntegrationData` structure

This is an unstructured list of XML elements with string values. There is no specific schema for this (as it is specific to the requirements of each vendor), and the content is effectively a name-value map. The content of each element is treated as an opaque string, and no data validation will occur.

The structure in this example is for ContactIntegrationData, and contains data stored by vendor AcmeLtd containing five settings.

<ContactIntegrationData>
  <VendorID>AcmeLtd</VendorID>
  <Alpha>true</Alpha>
  <Beta>992300</Beta>
  <Gamma>john.smith@example.org</Gamma>
  <Epsilon>2012-01-01T19:02:01+0100</Epsilon>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/acmeltd/"/>
</ContactIntegrationData>

HTTP GET

Returns a representation vendor-specific integration data associated with an entity.

Example

Retrieve the integration data for AcmeLtd persisted against contact with ID 562.

GET /api/2012-02-01/auth/resources/contacts/562/integrationdata/acmeltd/

<ContactIntegrationData>
  <VendorID>AcmeLtd</VendorID>
  <Uri>https://app.acmeltd.org/contacts/9943lkz0ll104/edit</Uri>
  <LastSynchronized>2012-01-01T19:02:01+0100</LastSynchronized>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/integrationdata/acmeltd/"/>
</ContactIntegrationData>

HTTP POST

Not supported.

HTTP PUT

Performs an update of vendor-specific integration data by replacing the entire representation with a new copy. If no previous vendor data exists at the URI, a new record is created.

Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for PUT operations are listed below.

Status	Description
200 OK	Resource was successfully updated.
400 Bad Request	HTTP request body contains malformed or invalid parameters.
409 Conflict	Resource could not be updated because it contains values that conflict with those on the server.

Example

Replace the integration data for AcmeLtd against contact with ID 562 with a new copy. If no integration data exists for the vendor, a record is created.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/integrationdata/acmeltd HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 1769

<ContactIntegrationData>
  <VendorID>AcmeLtd</VendorID>
  <LastSynchronized>2012-01-01T19:02:01+0100</LastSynchronized>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/integrationdata/acmeltd/"/>
</ContactIntegrationData>

HTTP DELETE

Not supported.

HTTP PATCH

Not supported.

IntegrationData collection resource

Resource URI

/api/2012-02-01/auth/resources/{ResourceType}/{ResourceID}/integrationdata/

Examples

URI integration data for a Contact:
/api/2012-02-01/auth/resources/contacts/99372/integrationdata/
URI integration data for an Organisation:
/api/2012-02-01/auth/resources/organisations/3264/integrationdata/

General structure

<IntegrationDataCollection>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Salesforce" type="application/xml" title="Salesforce" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/oracle/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Oracle" type="application/xml" title="Oracle" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/oracle/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/VendorX" type="application/xml" title="VendorX" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/vendorx/"/>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/2/integrationdata/"/>
</IntegrationDataCollection>

HTTP GET

Returns a representation of the collection as a set of Link elements which can be followed to access individual IntegrationData resources, or link expansion can be used via the expand query parameter to inline the entities with the HTTP GET response. See querying collections for general information on handling resource collections.

Optional parameters

Parameter	Description
expand	Expression referencing Link elements to expand when generating the response. See link expansion.
skip	Returns a subset of records from the collection, starting at index N+1 specified by this parameter. The `skip` and `top` parameters are generally used for collection paging.
top	Returns a subset of records from the collection, starting at index 0 or index `skip`, and returns the first N records. The `skip` and `top` parameters are generally used for collection paging.

Example 1

Retrieve a collection of IntegrationData links with the default parameters, and no link expansion.

GET /api/2012-02-01/auth/resources/contacts/211/integrationdata/

<IntegrationDataCollection>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Salesforce" type="application/xml" title="Salesforce" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/oracle/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Oracle" type="application/xml" title="Oracle" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/oracle/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/VendorX" type="application/xml" title="VendorX" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/vendorx/"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/"/>
</IntegrationDataCollection>

Example 2

Retrieve a collection of IntegrationData links with the default parameters, with Salesforce data link expansion.

GET /api/2012-02-01/auth/resources/contacts/211/integrationdata/?expand=Salesforce

<IntegrationDataCollection>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Salesforce" type="application/xml" title="Salesforce" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/oracle/">
    <ContactIntegrationData>
      <VendorID>AcmeLtd</VendorID>
      <LastSynchronized>2012-01-01T19:02:01+0100</LastSynchronized>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/acmeltd/"/>
    </ContactIntegrationData>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Oracle" type="application/xml" title="Oracle" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/oracle/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/VendorX" type="application/xml" title="VendorX" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/vendorx/"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/211/integrationdata/"/>
</IntegrationDataCollection>