REST Auth API: ResourceDescription

ResourceDescriptions provide metadata about resources, including details about their support for custom fields. Each description instance is specific to one type of resource, and provides the reference list of available fields that can be used with that resource.

This resource is important when using custom fields as it provides access to a list of available fields and thier identifiers for each type of resource.

This resource supports retrieval of a list field instances and updating existing field values.

Resource URI

This resource is available on contacts and organisations via the /describe/ URI.

/api/2012-02-01/auth/resources/{ResourceType}/describe/

Examples

URI for Contacts: /api/2012-02-01/auth/resources/contacts/describe/
URI for Organisations: /api/2012-02-01/auth/resources/organisations/describe/

General structure

This resource is represented by a list of Link elements referencing the different types of fields (built-in and custom) that define the resource.

<ResourceDescription>
  <Name>Contact</Name>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Fields" type="application/xml" title="Fields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/fields/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/CustomFields" type="application/xml" title="CustomFields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/customfields/"/>
</ResourceDescription>

Resource properties

Property	Description
Name	The descriptive name of the resource.

Link (title)	Description
Fields	Reference to a FieldDescription collection describing available built-in fields for the resource.
CustomFields	Reference to a FieldDescription collection describing available custom fields for the resource.

HTTP GET

Returns a representation of the ResourceDescription for a specific type of resource, including the properties and links above.

Optional parameters

Parameter	Description
expand	Expression referencing Link elements to expand when generating the response. See link expansion.

Example 1

Retrieve a resource description for the Contact resource.

GET /api/2012-02-01/auth/resources/contacts/describe/

<ResourceDescription>
  <Name>Contact</Name>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Fields" type="application/xml" title="Fields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/fields/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/CustomFields" type="application/xml" title="CustomFields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/customfields/"/>
</ResourceDescription>

Example 2

Retrieve a resource description for the Contact resource, with inline link expansion for custom fields.

GET /api/2012-02-01/auth/resources/contacts/describe/

<ResourceDescription>
  <Name>Contact</Name>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/?expand=customfields"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Fields" type="application/xml" title="Fields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/fields/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/CustomFields" type="application/xml" title="CustomFields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/customfields/">
    <FieldDescriptions>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/9989d626-848e-461b-a870-4dc6f095e4bc/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/247861ca-60c8-440f-a231-4204f0055552/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/204f7907-5e01-41f7-8742-5a68d320eff7/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/05240086-58de-4bfd-8965-bbc2d66331a8/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptionss/be174a8b-9804-45c9-8ecd-120cabf12e56/"/>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/customfields/"/>
    </FieldDescriptions>
  </Link>
</ResourceDescription>