Arlo

REST Auth API: FieldDescription

FieldDescription resources provide a central place that describes the metadata or schema used by individual custom fields, including their name, value type and other attributes such as labels or help text.

Whenever a new custom field is defined for use with a resource such as a Contact and Organisation, a new description record will be created for it.

This resource supports retrieval of specific instances field descriptions, and collection of all available fields on all resources.

FieldDescription instance resource

Resource URI

/api/2012-02-01/auth/resources/fielddescriptions/{UniqueIdentifier}/

General structure

<FieldDescription>
  <UniqueIdentifier>9adef7c7-fa50-4a3d-af4e-358bacbbd883</UniqueIdentifier>
  <ResourceType>Contact</ResourceType>
  <Name>MembershipType</Name>
  <IsEnabled>true</IsEnabled>
  <ValueType>
    <TypeName>String</TypeName>
    <IsArray>false</IsArray>
  </ValueType>
  <Attributes>
    <DefaultLabel>Membership type</DefaultLabel>
    <Description>Choose from the list of available options.</Description>
    <HelpText>Your membership type can be found on the front of your membership card. Contact our support team if you are not sure where you can find your membership type.</HelpText>
  </Attributes>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/SupportedValuesList" type="application/xml" title="SupportedValuesList" href="https://demo.arlo.co/api/2012-02-01/auth/resources/lists/438ed2ac-5f23-45dd-97cb-ef7e1809a0f1/"/>
</FieldDescription>

Resource properties

Property Description
UniqueIdentifier A GUID value that uniquely identifies this resource across any platform.
ResourceType A string representing the type of resource this field is associated with.
Name A string representing the system identifier for the field. Note this is distinct from the display label for the field.
IsEnabled A boolean indicating whether this field is enabled for use with new entities. Note that even if a field is not active, it may still describe data on historical resources, so will continue to be accessible via the API.
ValueType A structure describing the type of value stored by the field. Has two elements:
  • TypeName: Describes the raw value type. One of String, Boolean, Integer32, Date, DateTime.
  • IsArray: Boolean indicating whether the field stores multiple ordered values (an Array of values).
Attributes An unstructured map of additional values describing the field, including custom properties. Common attributes:
  • DefaultLabel: A displayable string to use when displaying this field in a UI. For example, Membership ID.
  • Description: A displayable string to use as a short hint when this field in a UI. For example, This should be a six-digit code.
  • HelpText: A displayable string to use as context-sensitive help text when displaying this field in a UI. For example, This value can be found on the front of your membership card. Contact our support team if you are not sure where you can find your membership ID.
Link (title) Description
SupportedValuesList Reference to List describing the supported values for this field. Used only if the field has a predefined or known set of acceptable values (such as a field designed to be visualised as a dropdown list). Omitted if the field accepts any value.

HTTP GET

Returns a representation of a specific field's metadata.

Example

GET /api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/

<FieldDescription>
  <UniqueIdentifier>9adef7c7-fa50-4a3d-af4e-358bacbbd883</UniqueIdentifier>
  <ResourceType>Contact</ResourceType>
  <Name>MembershipType</Name>
  <IsEnabled>true</IsEnabled>
  <ValueType>
    <TypeName>String</TypeName>
    <IsArray>false</IsArray>
  </ValueType>
  <Attributes>
    <DefaultLabel>Membership type</DefaultLabel>
    <Description>Choose from the list of available options.</Description>
    <HelpText>Your membership type can be found on the front of your membership card. Contact our support team if you are not sure where you can find your membership type.</HelpText>
  </Attributes>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/SupportedValuesList" type="application/xml" title="SupportedValuesList" href="https://demo.arlo.co/api/2012-02-01/auth/resources/lists/438ed2ac-5f23-45dd-97cb-ef7e1809a0f1/"/>
</FieldDescription>

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

HTTP PATCH

Not supported.

FieldDescription collection resource

Resource URI

Collections of fields are often obtained via a link from the ResourceDescription resource, as this is used to describe all known fields for different types of resources.

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

Examples

  • List custom fields for a Contact:
    /api/2012-02-01/auth/resources/contacts/describe/customfields/
  • List custom fields for a Organisation:
    /api/2012-02-01/auth/resources/organisations/describe/customfields/

General structure

<FieldDescriptions>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9989d626-848e-461b-a870-4dc6f095e4bc/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/247861ca-60c8-440f-a231-4204f0055552/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/204f7907-5e01-41f7-8742-5a68d320eff7/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/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>

HTTP GET

Returns a representation of the collection as a set of Link elements which can be followed to access individual FieldDescription 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 custom FieldDescription links for the Contact resource with the default parameters, and no link expansion.

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

<FieldDescriptions>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9989d626-848e-461b-a870-4dc6f095e4bc/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/247861ca-60c8-440f-a231-4204f0055552/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/204f7907-5e01-41f7-8742-5a68d320eff7/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/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>
Example 2

Retrieve a collection of FieldDescription links for custom fields defined for the Contact resource with the default parameters, with link expansion.

GET /api/2012-02-01/auth/resources/contacts/describe/customfields/?expand=fielddescription

<FieldDescriptions>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/">
    <FieldDescription>
      <UniqueIdentifier>9adef7c7-fa50-4a3d-af4e-358bacbbd883</UniqueIdentifier>
      <ResourceType>Contact</ResourceType>
      <Name>MembershipType</Name>
      <IsEnabled>true</IsEnabled>
      <ValueType>
        <TypeName>String</TypeName>
        <IsArray>false</IsArray>
      </ValueType>
      <Attributes>
        <DefaultLabel>Membership type</DefaultLabel>
        <Description>Choose from the list of available options.</Description>
        <HelpText>Your membership type can be found on the front of your membership card. Contact our support team if you are not sure where you can find your membership type.</HelpText>
      </Attributes>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9adef7c7-fa50-4a3d-af4e-358bacbbd883/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/SupportedValuesList" type="application/xml" title="SupportedValuesList" href="https://demo.arlo.co/api/2012-02-01/auth/resources/lists/438ed2ac-5f23-45dd-97cb-ef7e1809a0f1/"/>
    </FieldDescription>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9989d626-848e-461b-a870-4dc6f095e4bc/">
    <FieldDescription>
      <UniqueIdentifier>9989d626-848e-461b-a870-4dc6f095e4bc</UniqueIdentifier>
      <ResourceType>Contact</ResourceType>
      <Name>MembershipCode</Name>
      <IsEnabled>true</IsEnabled>
      <ValueType>
        <TypeName>String</TypeName>
        <IsArray>false</IsArray>
      </ValueType>
      <Attributes>
        <DefaultLabel>Membership code</DefaultLabel>
      </Attributes>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/9989d626-848e-461b-a870-4dc6f095e4bc/"/>
    </FieldDescription>
  </Link>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/describe/customfields/"/>
</FieldDescriptions>

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

HTTP PATCH

Not supported.