identity 1.0 documentation

Portable Contacts 1.0 Draft C

«  Electronic Authentication Guideline   ::   Contents   ::   Terms  »

Portable Contacts 1.0 Draft C

Based on Portable Contacts 1.0 Draft C August 5,2008 .

Abstract

The Portable Contacts specification is designed to make it easier for developers to give their users a secure way to access the address books and friends lists they have built up all over the web. Specifically, it seeks to create a common access pattern and contact schema that any site can provide, well-specified authentication and access rules, standard libraries that can work with any site, and absolutely minimal complexity, with the lightest possible toolchain requirements for developers.

By far the easiest way to start understanding this spec is to jump to the example in the Appendix. The format and meaning of the response should be readily apparent, and the majority of this document is merely an attempt to formalize the details of what should be relatively clear from this example.

Appendix A. Example

Here is a sample request and response that illustrates much of Portable Contacts. For simplicity, authorization information is not shown in the request.

Sample request (via HTTP GET):

http://sample.site.org/path/to/api/@me/@all?startIndex=10&count=10&sortBy=displayName

Sample response (JSON):

{
  "startIndex": 10,
  "itemsPerPage": 10,
  "totalResults": 12,
  "entry": [
    {
      "id": "123",
      "displayName": "Minimal Contact"
    },
    {
      "id": "703887",
      "displayName": "Mork Hashimoto",
      "name": {
        "familyName": "Hashimoto",
        "givenName": "Mork"
      },
      "birthday": "0000-01-16",
      "gender": "male",
      "drinker": "heavily",
      "tags": [
        "plaxo guy",
        "favorite"
      ],
      "emails": [
        {
          "value": "mhashimoto-04@plaxo.com",
          "type": "work",
          "primary": "true"
        },
        {
          "value": "mhashimoto-04@plaxo.com",
          "type": "home"
        },
        {
          "value": "mhashimoto@plaxo.com",
          "type": "home"
        }
      ],
      "urls": [
        {
          "value": "http://www.seeyellow.com",
          "type": "work"
        },
        {
          "value": "http://www.angryalien.com",
          "type": "home"
        }
      ],
      "phoneNumbers": [
        {
          "value": "KLONDIKE5",
          "type": "work"
        },
        {
          "value": "650-123-4567",
          "type": "mobile"
        }
      ],
      "photos": [
        {
          "value": "http://sample.site.org/photos/12345.jpg",
          "type": "thumbnail"
        }
      ],
      "ims": [
        {
          "value": "plaxodev8",
          "type": "aim"
        }
      ],
      "addresses": [
        {
          "type": "home",
          "streetAddress": "742 Evergreen Terrace\nSuite 123",
          "locality": "Springfield",
          "region": "VT",
          "postalCode": "12345",
          "country": "USA",
          "formatted": "742 Evergreen Terrace\nSuite 123\nSpringfield, VT 12345 USA"
        }
      ],
      "organizations": [
        {
          "name": "Burns Worldwide",
          "title": "Head Bee Guy"
        }
      ],
      "accounts": [
        {
          "domain": "plaxo.com",
          "userid": "2706"
        }
      ]
    }
  ]
}

Sample response (XML):

<response>

 <startIndex>10</startIndex>
 <itemsPerPage>10</itemsPerPage>
 <totalResults>12</totalResults>
 <entry>

  <id>123</id>
  <displayName>Minimal Contact</displayName>
 </entry>
 <entry>
  <id>703887</id>

  <displayName>Mork Hashimoto</displayName>
  <name>
   <familyName>Hashimoto</familyName>
   <givenName>Mork</givenName>

  </name>
  <birthday>0000-01-16</birthday>
  <gender>male</gender>
  <drinker>heavily</drinker>

  <tags>plaxo guy</tags>
  <tags>favorite</tags>
  <emails>
   <value>mhashimoto-04@plaxo.com</value>

   <type>work</type>
   <primary>true</primary>
  </emails>
  <emails>
   <value>mhashimoto-04@plaxo.com</value>

   <type>home</type>
  </emails>
  <emails>
   <value>mhashimoto@plaxo.com</value>
   <type>home</type>

  </emails>
  <urls>
   <value>http://www.seeyellow.com</value>
   <type>work</type>
  </urls>

  <urls>
   <value>http://www.angryalien.com</value>
   <type>home</type>
  </urls>
  <phoneNumbers>

   <value>KLONDIKE5</value>
   <type>work</type>
  </phoneNumbers>
  <phoneNumbers>
   <value>650-123-4567</value>

   <type>mobile</type>
  </phoneNumbers>
  <photos>
   <value>http://sample.site.org/photos/12345.jpg</value>
   <type>thumbnail</type>

  </photos>
  <ims>
   <value>plaxodev8</value>
   <type>aim</type>
  </ims>

  <addresses>
   <type>home</type>
   <streetAddress><![CDATA[742 Evergreen Terrace
Suite 123]]></streetAddress>
   <locality>Springfield</locality>

   <region>VT</region>
   <postalCode>12345</postalCode>
   <country>USA</country>
   <formatted><![CDATA[742 Evergreen Terrace
Suite 123
Springfield, VT 12345 USA]]></formatted>

  </addresses>
  <organizations>
   <name>Burns Worldwide</name>
   <title>Head Bee Guy</title>
  </organizations>

  <accounts>
   <domain>plaxo.com</domain>
   <userid>2706</userid>
  </accounts>
 </entry>

</response>

Appendix B. Compatibility with OpenSocial

This version of the Portable Contacts specification is currently wire-compatible with the overlapping portion of the OpenSocial RESTful Protocol version 0.8.1 [OpenSocial]. Specifically, any compliant OpenSocial RESTful Protocol 0.8.1 Provider is also a compliant Portable Contacts Provider, because they are specified to use the same Authorization methods (OAuth), Additional Path Information, Query Parameters, and Contact Schema. The OpenSocial and Portable Contacts communities chose to wire-align our respective specs in order to maximize widespread adoption of a single API for accessing people data.

It is our intention to maintain this compatibility going forward, so long as it is feasible, and so long as the changes required are compatible with the Goals and Approach of this spec. Although Portable Contacts is an independent spec, with a more limited scope than OpenSocial, any proposed changes to either this Portable Contacts spec or the OpenSocial RESTful Protocol should be considered in the context of both communities, and we should strive not to break compatibility unless it is truly necessary, e.g. if the goals of the two communities diverge significantly in the future.

Note

POCO is mentioned on Reserved member definitions on OPENID-SPECS-AB.

«  Electronic Authentication Guideline   ::   Contents   ::   Terms  »