idnits 2.17.1 draft-smarr-vcarddav-portable-contacts-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1388. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1399. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1406. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1412. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document date (December 2, 2008) is 5621 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2425 (Obsoleted by RFC 6350) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Smarr 3 Internet-Draft Plaxo 4 Intended status: Informational December 2, 2008 5 Expires: June 5, 2009 7 Portable Contacts: A Common Format and Protocol for Accessing Contacts 8 draft-smarr-vcarddav-portable-contacts-00 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on June 5, 2009. 35 Abstract 37 This document specifies Portable Contacts, XML and JSON address book 38 document formats and an interface for accessing address book and 39 friends-list information over HTTP. 41 Table of Contents 43 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 44 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 3 45 1.2. Approach . . . . . . . . . . . . . . . . . . . . . . . . . 4 46 1.3. Feedback . . . . . . . . . . . . . . . . . . . . . . . . . 4 47 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 5 48 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 49 4. Workflow Overview . . . . . . . . . . . . . . . . . . . . . . 6 50 5. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 6 51 6. Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . 7 52 6.1. Authentication and Authorization . . . . . . . . . . . . . 7 53 6.1.1. Delegated Authorization . . . . . . . . . . . . . . . 8 54 6.1.2. Direct Authorization . . . . . . . . . . . . . . . . . 8 55 6.1.3. Available Authorization Methods . . . . . . . . . . . 8 56 6.2. Additional Path Information . . . . . . . . . . . . . . . 9 57 6.3. Query Parameters . . . . . . . . . . . . . . . . . . . . . 9 58 6.3.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 10 59 6.3.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 12 60 6.3.3. Pagination . . . . . . . . . . . . . . . . . . . . . . 12 61 6.3.4. Presentation . . . . . . . . . . . . . . . . . . . . . 13 62 6.3.5. Declining to honor query parameters . . . . . . . . . 14 63 6.4. Response Format . . . . . . . . . . . . . . . . . . . . . 14 64 6.5. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 15 65 7. Contact Schema . . . . . . . . . . . . . . . . . . . . . . . . 16 66 7.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 17 67 7.2. entry Element . . . . . . . . . . . . . . . . . . . . . . 17 68 7.2.1. Singular Fields . . . . . . . . . . . . . . . . . . . 17 69 7.2.2. Plural Fields . . . . . . . . . . . . . . . . . . . . 19 70 7.3. name Element . . . . . . . . . . . . . . . . . . . . . . . 22 71 7.4. address Element . . . . . . . . . . . . . . . . . . . . . 22 72 7.5. organization Element . . . . . . . . . . . . . . . . . . . 23 73 7.6. account Element . . . . . . . . . . . . . . . . . . . . . 24 74 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 76 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . . 24 77 Appendix B. Compatibility with OpenSocial . . . . . . . . . . . . 29 78 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 79 10.1. Normative References . . . . . . . . . . . . . . . . . . . 29 80 10.2. Informative References . . . . . . . . . . . . . . . . . . 29 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 30 82 Intellectual Property and Copyright Statements . . . . . . . . . . 31 84 1. Introduction 86 The Portable Contacts specification is designed to make it easier for 87 developers to give their users a secure way to access the address 88 books and friends lists they have built up all over the web. 89 Specifically, it seeks to create a common access pattern and contact 90 schema that any site can provide, well-specified authentication and 91 access rules, standard libraries that can work with any site, and 92 absolutely minimal complexity, with the lightest possible toolchain 93 requirements for developers. 95 By far the easiest way to start understanding this spec is to jump to 96 the example in the Appendix. The format and meaning of the response 97 should be readily apparent, and the majority of this document is 98 merely an attempt to formalize the details of what should be 99 relatively clear from this example. 101 This API defines a language- and platform- neutral protocol for 102 Consumers to request address book, profile, and friends-list 103 information from Service Providers. As a protocol, it is intended to 104 be easy to understand and implement, either as a Service Provider or 105 Consumer, using any language or platform of choice. It is also 106 intended to be implemented by both individuals and small services as 107 well as large providers, in any case where a service contains data 108 about who a user knows and wishes to make that information portable, 109 under the user's control. 111 While there are currently standards for describing contact info (such 112 as vCard), these standards do not specify how to discover, access, 113 and manipulate this information, and they do not capture the full 114 range of information typically found in modern address book and 115 social networking applications. Several large companies have also 116 released their own non-standard APIs for accessing and interacting 117 with contact information, increasing the burden on developers and 118 Consumers who wish to support most or all Service Providers. Nor do 119 these APIs inform other providers as to how they should construct 120 similar APIs. Thus Portable Contacts is an attempt to specify a 121 complete, modern, and straight-forward recipe for Service Providers 122 and Consumers of all sizes to make available and consume contact data 123 in a standardized way. 125 1.1. Goals 127 The goal of Portable Contacts is to make it easier for developers to 128 give their users a secure way to access the address books and friends 129 lists they have built up all over the web. Specifically, we seek to 130 create: 132 o A common access pattern and contact schema that any Service 133 Provider can implement 135 o Well-specified authorization and access rules 137 o Free and open source libraries in many languages for most popular 138 platforms 140 o Community-sourced support, documentation, and collaborative tools 142 o and absolutely minimal complexity, with the lightest possible 143 toolchain requirements for developers. 145 A measure of our success will be the elimination of the "password 146 anti-pattern," by making it far easier to implement Portable Contacts 147 than to engage in scraping, as well as a dramatic increase in the 148 number of sites that both provide and consume who-you-know data. 150 1.2. Approach 152 Our design is focused around ease of adoption, which means a few 153 things: 155 1. First, our emphasis is on simplicity of design and targeted use 156 cases, keeping our scope intentionally narrow at the outset. For 157 example, version 1 is simply about access, and defers for now on 158 the more complex issues around update and sync. 160 2. Second, we're taking a modern approach to who-you-know data by 161 unifying traditional contact information and social network data, 162 in order to properly represent the current diversity of the 163 social web ecosystem. 165 3. Third, we're reusing existing standards wherever possible, 166 including vCard, OpenSocial, XRDS-Simple, OAuth, etc. 168 4. And lastly, we're designing something that should be easy for 169 current service providers to adopt. We started with a review of 170 all the major existing contacts APIs and targeted common 171 capabilities that they all share and provide. We believe this 172 pragmatic balance is the best and quickest way to achieve our 173 intended goal of widespread adoption. 175 1.3. Feedback 177 The Portable Contact specification is currently being developed on 178 the http://groups.google.com/group/portablecontacts mailing list, 179 with additional feedback coming from the OpenSocial community. 181 Feedback can be posted to the Portable Contacts list or directly to 182 the author. If you encounter any problems with joining the list, 183 please contact the author. 185 2. Notational Conventions 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 189 document are to be interpreted as described in [RFC2119]. 191 3. Definitions 193 Contact: A record describing information about a particular person 194 or entity, consisting of contact information (e.g. name, e-mail 195 addresses, phone numbers) and other descriptive information, as is 196 typically found in address book and social networking 197 applications. 199 Service Provider: A web application that provides Contact 200 information via the Portable Contacts protocol. 202 Consumer: A website or application that uses the Portable Contacts 203 protocol to request contacts managed by the Service Provider. 205 Base URL: The root endpoint URL specified by the Service Provider 206 during Discovery and used to make requests. Consumers MAY append 207 additional path information and query string parameters to this 208 URL as part of the request. 210 Singular Field: A contact field that can appear at most once per 211 contact, e.g. "displayName" or "gender". 213 Plural Field: A contact field that can appear multiple times per 214 contact, e.g. "emails" or "tags". 216 Simple Field A Singular Field or Plural Field whose value is a 217 single string attribute (see Section 7.1). 219 Complex Field A Singular Field or Plural Field whose value is an 220 object containing multiple sub-field attributes (see Section 7.1). 222 Canonical Value: Specified string values for string-valued contact 223 fields that represent common values in a canonical form, e.g. 224 "male" and "female" for "gender". Service Providers SHOULD 225 conform to Canonical Values if appropriate, but MAY deviate if 226 they need to represent additional values. 228 Primary Sub-Value: The sub-field in a Complex Field that should be 229 used when sorting or filtering by that field. Unless otherwise 230 specified, the "value" sub-field is always the Primary Sub-Field. 232 4. Workflow Overview 234 A Consumer wishing to access a user's data via Portable Contacts must 235 start with an Initial Identifier for the Service Provider containing 236 the user's data, usually provided by the user. In many cases, this 237 may be the domain name of the Service Provider's web site, such as 238 sample.site.org, but may be a more specific URL, such as the OpenID 239 identifier of the user, if available. Consumers then perform 240 Discovery on the Initial Identifier to determine where the Portable 241 Contacts endpoint for this Service Provider resides. If successful, 242 the Consumer may then attempt to request information from that 243 endpoint. If the endpoint contains private data, the Service 244 Provider will return an authorization challenge, and the Consumer 245 must then guide the user through an appropriate authorization flow to 246 obtain the credentials necessary to access this private data. Upon 247 successful authorization, the Consumer may request data from the 248 Portable Contacts endpoint using these authorization credentials. 249 Whether accessing public or private data, Consumers may request a 250 specific subset of the user's data using standard Query Parameters. 251 Upon a successful request, the data is returned in the response, and 252 the Consumer may then parse the response data and use it as desired. 253 The following sections detail each of these steps. 255 5. Discovery 257 Portable Contacts API endpoint is discoverable from the domain root 258 using [XRDS-Simple] (previously known as YADIS). The API is 259 identified by the Service Type http://portablecontacts.net/spec/1.0 260 and the corresponding URI is the Base URL for the API. The Base URL 261 MUST NOT contain any query string, as additional path information and 262 query string variables MAY be appended by Consumers as part of 263 forming the request (as described in detail below). 265 An example XRDS-Simple document describing the availability and 266 location of a Portable Contacts endpoint might look like this: 268 269 271 xri://$xrds*simple 272 273 http://portablecontacts.net/spec/1.0 274 http://sample.site.org/path/to/api/ 275 276 277 279 In addition to discovering the endpoint itself, Service Providers 280 using OAuth to protect responses MUST also support OAuth Discovery, 281 as described in Section 6.1. 283 6. Invocation 285 All requests to the Service Provider are made as HTTP GET operations 286 on a URL deriving from the Base URL specified in Section 5. 287 Consumers MAY append additional path information and/or query string 288 parameters to the Base URL as part of the request, as specified in 289 Section 6.3. Additionally, authentication information MAY be sent 290 via POST data or additional HTTP headers in the request, as specified 291 in Section 6.1. Responses are returned in the body of the HTTP 292 response, formatted as JSON or XML, depending on what is requested. 293 Response and error codes SHOULD be transmitted via the HTTP status 294 code of the response (if possible), and SHOULD also be specified in 295 the body of the response, as described in Section 6.4 and 296 Section 6.5. Since the API endpoint is dynamic (and not serving 297 static content), Consumers MUST NOT interpret any cache headers in 298 the response as having meaning concerning when the same URL request 299 might return a different response upon subsequent invocation. 301 6.1. Authentication and Authorization 303 The data returned by a Portable Contacts endpoint MAY contain public 304 data, or it MAY contain private data. If the data returned is 305 public, no authentication or authorization is required. In most 306 cases however, the data returned is not public, and Service Providers 307 SHOULD ensure that the user has given prior consent, either 308 explicitly or implicitly, for their information to be released by 309 this API. Typically this is done by Consumers obtaining either 310 Direct Authorization (with raw credentials, for example the user's 311 username and password) or Delegated Authorization (with an access 312 token obtained out-of-band by the user, and given to the Consumer to 313 present as part of the request). Portable Contacts specifies 314 standard mechanisms for both types of authorization, so that 315 Consumers may be able to obtain private data on a user's behalf from 316 Service Providers in an automated and consistent fashion. Regardless 317 of the Authorization method used, the context of the request (i.e. 318 the user for whom data is being requested) MUST be inferred by 319 Service Providers from the Base URL and the authorization credentials 320 provided. If public data is being accessed (and no authorization is 321 provided), the Base URL MUST contain enough information for Service 322 Providers to know which data to return, but if private data is being 323 accessed (and authorization is provided), the same Base URL MAY 324 return information for different users depending on the authorization 325 credentials provided. 327 6.1.1. Delegated Authorization 329 Service Providers wishing to provide Delegated Authorization MUST 330 support [OAuth Core 1.0] as an OAuth Service Provider, and MAY also 331 support additional Delegated Authorization mechanisms, if they 332 choose. Service Providers supporting OAuth MUST also support [OAuth 333 Discovery] to facilitate automatic discovery of authorization 334 endpoints for Consumers. Service Providers SHOULD provide a 335 mechanism for Consumers to automatically obtain a Consumer Key and 336 Consumer Secret, but MAY require this to be done out-of-band. 338 6.1.2. Direct Authorization 340 Service Providers wishing to provide Direct Authorization MUST 341 support HTTP Basic Access Authentication [RFC2617], and MAY also 342 support additional Direct Authorization mechanisms, if they choose. 343 In addition to being a well-established mechanism for Direct 344 Authorization, HTTP Basic has the added benefit of being understood 345 by most Web Browsers, and can prompt users to enter their credentials 346 as part of accessing a resource protected in this manner. There are 347 also convenient ways of providing and parsing HTTP Basic credentials 348 in popular tools and libraries like curl and PHP. 350 6.1.3. Available Authorization Methods 352 Service Providers that provide access to private data MAY choose not 353 to support either Direct Authorization or Delegated Authorization, 354 depending on their security requirements, but they MUST support 355 either OAuth or HTTP Basic auth if they require any Authorization. 356 When accessing a Portable Contacts endpoint, if sufficient 357 authorization credentials are not provided, the Service Provider 358 SHOULD return a 401 Unauthorized response, and SHOULD provide the 359 available Authorization mechanisms available by including WWW- 360 Authenticate headers in the response for each type of Authorization 361 method supported (as defined in [RFC2616], section 14.47. Consumers 362 will then be able to recognize that the API is a protected resource 363 and initiate the proper Authorization process needed to obtain the 364 appropriate credentials. An example set of WWW-Authenticate headers 365 returned by a Service Provider that supports both OAuth and HTTP 366 Basic might look like this. Note that the realm value is intended to 367 be an opaque string that merely defines a shared label for resources 368 that share the same authorization requirements. 370 WWW-Authenticate: OAuth realm="sample.site.org" 371 WWW-Authenticate: Basic realm="sample.site.org" 373 If Service Providers wish to make some response data publicly 374 available and also provide additional info given the proper 375 authorization credentials, they SHOULD provide a 200 OK response to 376 requests without authorization with a WWW-Authenticate header in the 377 response indicating that additional info is available via the 378 specified authorization mechanisms. 380 6.2. Additional Path Information 382 A request using the Base URL alone MUST yield a result, assuming that 383 adequate authorization credentials are provided. In addition, 384 Consumers MAY append additional path information to the Base URL to 385 request more specific information. Service Providers MUST recognize 386 the following additional path information when appended to the Base 387 URL, and MUST return the corresponding data: 389 o "/@me/@all" -- Return all contact info (equivalent to providing no 390 additional path info) 392 o "/@me/@all/{id}" -- Only return contact info for the contact whose 393 "id" value is equal to the provided "{id}", if such a contact 394 exists. In this case, the response format is the same as when 395 requesting all contacts, but any contacts not matching the 396 requested ID MUST be filtered out of the result list by the 397 Service Provider 399 o "/@me/@self" -- Return contact info for the owner of this 400 information, i.e. the user on whose behalf this request is being 401 made. In this case, the response format is the same as when 402 requesting all contacts, but any contacts not matching the 403 requested ID MUST be filtered out of the result list by the 404 Service Provider. 406 6.3. Query Parameters 408 Portable Contacts defines a standard set of operations that can be 409 used to filter, sort, and paginate response results. The operations 410 are specified by adding query parameter to the Base URL, either in 411 the query string or as HTTP POST data. Providers MAY support 412 additional query parameters not specified here, and Providers SHOULD 413 ignore any query parameters they don't recognize. 415 6.3.1. Filtering 417 Filtering is used to limit the request results to Contacts that match 418 given criteria. Content filtering is accomplished by combining three 419 request parameters: 421 filterBy: Specifies the field name to filter by. If the specified 422 field is a Plural Field, the Contact SHALL match if any of the 423 instances of the given field match the specified criterion (e.g. 424 if a contact has multiple "emails" values, only one has to match 425 for the entire Contact to match). If a Simple Field is specified, 426 its value must match the specified "filterValue" according to the 427 specified "filterOp". If a Complex Field is specified, its 428 Primary Sub-Field must match. If the specified field is not a 429 direct child of the "entry" element, the full path MUST be 430 specified using the '.' character as separator. For example, to 431 filter by gender the parameter value is "gender" and to filter by 432 first name, the parameter value is "name.givenName". 434 filterOp: Specifies the comparison method used to evaluate the field 435 value with the value of the filter criterion. Providers SHOULD 436 support the following values: 438 * "equals": the two values must be identical strings. 440 * "contains": the entire "filterValue" must be a substring of the 441 Contact field value. 443 * "startswith": the entire "filterValue" must be a substring of 444 the Contact field value, starting at the beginning of the field 445 value. This criterion is satisfied if the two strings are 446 equal. 448 * "present": a Contact matches the criterion if the field 449 specified by "filterBy" has a non-empty value, or if it 450 contains a non-empty node for complex fields. 452 Providers MAY support additional filter operations if they choose. 453 Providers MUST decline to filter results if the specified filter 454 operation is not recognized (as per Section 6.3.5). 456 filterValue: Specifies the value to filter by, using the comparison 457 method defined by "filterOp". 459 In addition, requests can filter content based on their "update" 460 timestamp: 462 updatedSince: Returns only contacts that have been modified on or 463 after the given time, specified as an xs:dateTime. The filter is 464 based on the value of the "updated" field, and can be used 465 independently of other filters or combined. It enables a basic 466 syndication pattern when accessing the same data over time. The 467 first API call returns all data, which can be stored locally. 468 Subsequent API calls can specify "updatedSince" with the time of 469 the last API call, so that only contacts that have been added or 470 modified since the last API call will be returned. 472 Here are a few illustrative examples of filtering matches with 473 "filterBy", "filterOp", and "filterValue". In each case, assume the 474 following two contacts would be returned if no filtering parameters 475 were provided: 477 { 478 "id": "1", 479 "displayName": "Chris Messina", 480 "urls": [ 481 { "value": "http://factoryjoe.com/blog", "type": "blog" } 482 ] 483 }, 484 { 485 "id": "2", 486 "displayName": "Joseph Smarr", 487 "emails": [ 488 { "value": "joseph@plaxo.com", "type": "work", "primary": "true" }, 489 { "value": "jsmarr@gmail.com", "type": "home" } 490 ], 491 } 493 Given the parameters 494 "filterBy=displayName&filterOp=startswith&filterValue=Chr", only the 495 first contact (with id=1) would match and be returned. However, with 496 parameters "filterBy=displayName&filterOp=present", both contacts 497 would be returned. Given the parameters 498 "filterBy=email&filterOp=contains&filterValue=plaxo.com", only the 499 second contact (with id=2) would match, as would it be the only 500 contact to match given the parameters 501 "filterBy=email&filterOp=present". 503 If a request specifies a "filterValue" but no "filterBy" or 504 "filterOp", it is up to the Provider how to interpret this filter 505 request. Providers MAY choose to default to filtering by a given 506 field (e.g. "displayName"); they MAY choose to implement a custom, 507 Provider-specific query syntax for "filterValue" in this case; or 508 they MAY choose to reject requests of this type. In general, if 509 Consumers want to request specific behavior from Providers, they 510 should do so by being explicit in their use of query parameters. 512 6.3.2. Sorting 514 Sorting allows requests to specify the order in which contacts are 515 returned. 517 sortBy Specifies the field name whose value SHALL be used to order 518 the returned Contacts. The sort order is determine by the 519 "sortOrder" parameter. If "sortBy" is a Singular Field, contacts 520 are sorted according to that field's value; if it's a Plural 521 Field, contacts are sorted by the Value (or Major Value, if it's a 522 Complex Field, see Section 7) of the field marked with "primary": 523 "true", if any, or else the first value in the list, if any, or 524 else they are sorted last if the given contact has no data for the 525 given field. 527 sortOrder The order in which the "sortBy" parameter is applied. 528 Allowed values are "ascending" and "descending". If a value for 529 "sortBy" is provided and no "sortOrder" is specifies, the 530 "sortOrder" SHALL default to "ascending". Sort order is expected 531 to be case-insensitive Unicode alphabetic sort order, with no 532 specific locale implied. 534 6.3.3. Pagination 536 The pagination parameters can be used together to "page through" a 537 large number of results in manageable chunks: 539 startIndex: Specifies the offset of the first result to be returned 540 with respect to the list of contacts that would be returned if no 541 "startIndex" were provided. For instance, if in a given request 542 10 contacts would normally be provided, if "startIndex" is 7 and 543 no "count" is specified, then only the last 3 contacts in that 544 list would be returned (contacts are zero-indexed). If 545 "startIndex" is greater than or equal to the total number of 546 results that would be returned, no contacts are returned. Value 547 MUST be a non-negative integer and defaults to 0 if no value is 548 specified. 550 count: If non-zero, specifies the maximum number of contacts the 551 Consumer would like the Provider to return at a time. Value MUST 552 be a non-negative integer and defaults to 0 if no value is 553 specified. A "count" of 0 means that is up to the Provider to 554 determine how many contacts to return by default (some Providers 555 may return all contacts by default; others may return a fixed 556 default number like 10). Providers SHOULD honor a very large 557 "count" value, and SHOULD support returning all contacts at once 558 when presented with a "count" request that is larger than the 559 number of contacts the user has, but Providers MAY choose to never 560 return more than a Provider-determined maximum number of contacts 561 per request, if returning all contacts is too burdensome. In all 562 cases, at most "count" contacts SHALL be returned, starting at 563 "startIndex" and counting up from there. In each of these cases, 564 Providers MUST indicate the total number of contacts they chose to 565 return in the response using the "itemsPerPage" response element 566 (see Section 6.4). 568 For instance, on an initial query, specifying "startIndex=0&count=10" 569 will return only the first 10 results. The total number of possible 570 results is indicated by the "totalResults" field of results, so the 571 client knows how many "pages" of results exist. A subsequent query 572 of "startIndex=10&count=10" will return the next 10 results, and so 573 on. 575 6.3.4. Presentation 577 Presentation controls the format, makeup, and delivery mechanism for 578 returning the requested result set: 580 fields: If non-empty, each contact returned SHALL contain only the 581 fields explicitly requested. Service Provider MAY return a subset 582 of the requested fields if they are not supported. This field is 583 used for efficiency when the client only wishes to access a subset 584 of the fields normally returned in results. Value is a comma 585 separated list of top level field names (e.g. 586 "id,name,emails,photos") and defaults to an empty list which means 587 it's up to the Provider which fields to return. Consumers may 588 request all available fields to be returned by using the special 589 value "@all". 591 format: Specifies the format in which the response data is returned. 592 Service Providers MUST support the values "json" for JSON 593 (http://json.org) and "xml" for XML (http://www.w3.org/XML/) and 594 MAY support additional formats if desired. The format defaults to 595 "json" if no format is specified. The data structure returned is 596 equivalent in both formats; the only difference is in the encoding 597 of the data. Singular Fields are encoded as string key/value 598 pairs in JSON and tags with text content in XML, e.g. ""field": 599 "value"" and "value" respectively. Plural Fields 600 and Plural Bundles are encoded as arrays in JSON and repeated tags 601 in XML, e.g. ""fields": [ "value1", "value2" ]" and 602 "value1value2" respectively. 603 Nodes with multiple sub-nodes are represented as objects in JSON 604 and tags with sub-tags in XML, e.g. ""field": { "subfield1": 605 "value1", "subfield2": "value2" }" and "value1value2" respectively. 608 6.3.5. Declining to honor query parameters 610 Providers SHOULD honor all filtering, sorting, and pagination 611 requests specified via Query Parameters. However, in some instances 612 it may be too burdensome to comply with a particular request, e.g. 613 because the Provider does not have an efficient database index set up 614 for a given field that is requested for filtering or sorting, and is 615 unable to efficiently fetch all data and post-process the results to 616 honor the request before returning the response. In such cases, 617 Providers MAY decline to honor the request (or specific pieces of the 618 request). If any part of the request is declined, Providers MUST 619 specify which part(s) of the request were declined in the response, 620 using ""sorted": false", ""filtered": false", and/or ""updatedSince": 621 false" as appropriate. For efficiency, Providers SHOULD omit these 622 response fields if that part of the request was successfully 623 performed, or if no such Query Parameter was specified in the 624 request. 626 Note that since all of the filtering, sorting, and pagination 627 operations are designed to reduce the amount of data returned, it is 628 possible for Consumers to emulate these operations client-side when a 629 Provider declines to perform them server-side. For instance, 630 filtering can be accomplished by iterating through each entry 631 returned and deleting those that do not match the filtering criteria. 632 Thus Consumers can request these operations to be performed server- 633 side, and Providers will honor them if possible, and otherwise 634 indicate to Consumers that they need to be performed client-side, 635 effectively "splitting the workload" while maintaining consistent 636 semantics. 638 6.4. Response Format 640 The structure of the response object returned from a successful 641 request is as follows. The root element is "response", which is 642 shown explicitly as the root element in XML format, and is the 643 anonymous root object returned when the format is JSON (i.e. in JSON, 644 the response returned is the object value of the "response" node). 645 The "response" node MUST contain the following child nodes, and MAY 646 contain additional nodes that the Service Provider wishes to add to 647 expose additional data. Note that "startIndex", "itemsPerPage", and 648 "totalResults" are based on [OpenSearch]. See the Appendix for a 649 full example. 651 o "startIndex": the index of the first result returned in this 652 response, relative to the starting index of all results that would 653 be returned if no "startIndex" had been requested. In general, 654 this will be equal to the value requested by the "startIndex", or 655 0 if no specific "startIndex" was requested. 657 o "itemsPerPage": the number of results returned per page in this 658 response. In general, this will be equal to the "count" Query 659 Parameter, but MAY be less if the Service Provider is unwilling to 660 return as many results per page as requested, or if there are less 661 than the requested number of results left to return when starting 662 at the current "startIndex". This field MUST be present if and 663 only if a value for "count" is specified in the request. 665 o "totalResults": the total number of contacts that would be 666 returned if there were no "startIndex" or "count" specified. This 667 value tells the Consumer how many total results to expect, 668 regardless of the current pagination being used, but taking into 669 account the current filtering options in the request. 671 o "entry": an array of Contact objects, one for each contact 672 matching the request, as defined in Section 7.2. For consistency 673 of parsing, if the request could possibly return multiple contacts 674 (as is normally the case), this value MUST always be an array of 675 results, even if there happens to be 0 or 1 matching results. If 676 the request is specifically for a single contact (e.g. because the 677 request contains Additional Path Information like "/@me/@all/{id}" 678 or "/@me/@self"), then "entry" MUST be an object containing the 679 single contact returned (i.e. ""entry": [ { /* first contact */ } 680 ]" and ""entry": { /* only contact */ }" respectively). 682 6.5. Error Codes 684 The Service Provider MUST return a response code with every response. 685 Response codes are numeric and conform to existing HTTP response 686 codes where possible, as defined below. In addition to the response 687 code, Service Providers SHOULD also provide a human-readable reason 688 that explains the reason for the response code. This message SHOULD 689 be intelligible to developers, but MAY be unsuitable for display to 690 end-users. Clients SHOULD provide their own appropriate error 691 message to users when encountering an error response. 693 Service Providers SHOULD conform to the following response codes to 694 indicate the following situations. Service Providers MAY return 695 additional codes to indicate additional information, but are 696 discouraged from doing so and should instead augment the reason text 697 with existing codes, if possible. 699 200: OK (response returned successfully) 701 400: Bad Request (request was malformed or illegal and cannot be 702 completed) 704 401: Unauthorized (authentication headers / parameters were invalid 705 or missing) 707 404: Not Found (the request points to an object that does not exist, 708 e.g. to an unknown contact id; note that Service Providers MUST 709 return a 200 with an empty array of contacts if the request has 710 filtering parameters that are valid but have no matches) 712 500: Internal Server Error (un unexpected error occurred during 713 processing) 715 503: Service Unavailable (service is temporarily unavailable; this 716 may be because the Consumer has exceeded their rate-limit of 717 requests) 719 7. Contact Schema 721 The Contact schema defines the containers and attributes used to 722 deliver an individual Contact or a list of Contacts as requested by 723 the Consumer. The traditional contact info fields were taken 724 directly from the vCard spec where possible [RFC2425], though 725 instances of vCard's archaic spellings were modernized (e.g. 726 "addresses" instead of "adr"). Even with the spelling updates, the 727 field mappings remain equivalent, which means it should be easy to 728 convert Portable Contacts data to and from vCard. By convention, 729 Singular Fields have singular spelling (e.g. "displayName") and 730 plural fields have plural spelling (e.g. "phoneNumbers") to make it 731 easy to distinguish them. 733 Each contact returned MUST include the "id" and "displayName" fields 734 with non-empty values, but all other fields are optional, and it is 735 recognized that not all Service Providers will be able to provide 736 data for all the supported fields. The field list below is broad so 737 that, for Service Providers that do support any of these fields, 738 there is a standard field name available. 740 7.1. Structure 742 Each field is defined as either a Singular Field, in which case there 743 MUST NOT be more than one instance of that field per contact, or as a 744 Plural Field, in which case any number of instances of that field MAY 745 be present per contact. 747 Contact information is formatted using labeled attributes with either 748 structured or unstructured string data. Each attribute value 749 consists of one of the following types: 751 Simple: A single string attribute which MAY specify a REQUIRED data 752 format or allow any string. A simple field MAY contain Canonical 753 Values specified, in which case Service Providers SHOULD try to 754 conform to those values if appropriate, but MAY provide alternate 755 string values to represent additional values. 757 Boolean: A special case of a Simple Field with two legal values: 758 "true" and "false". Values are case-sensitive. 760 Complex: A multi-value attribute containing any combination of other 761 attributes. Complex attributes are defined by listing the child 762 attributes and their types. For most Complex Fields, the "value" 763 sub-field contains the Major Value of that field (i.e. the primary 764 piece of contact information described by that field), and the 765 other fields provide additional meta-data. 767 7.2. entry Element 769 Unless otherwise specified, all fields are optional and of type xs: 770 string. Also, unless specified, all field values MUST NOT contain 771 any newline characters (\r or \n). 773 7.2.1. Singular Fields 775 id: Unique identifier for the Contact. Each Contact returned MUST 776 include a non-empty "id" value. This identifier MUST be unique 777 across this user's entire set of Contacts, but MAY not be unique 778 across multiple users' data. It MUST be a stable ID that does not 779 change when the same contact is returned in subsequent requests. 780 For instance, an e-mail address is not a good id, because the same 781 person may use a different e-mail address in the future. Usually, 782 in internal database ID will be the right choice here, e.g. 783 ""12345"". 785 displayName: The name of this Contact, suitable for display to end- 786 users. Each Contact returned MUST include a non-empty 787 "displayName" value. The name SHOULD be the full name of the 788 Contact being described if known (e.g. "Joseph Smarr" or "Mr. 789 Joseph Robert Smarr, Esq."), but MAY be a username or handle, if 790 that is all that is available (e.g. "jsmarr"). The value provided 791 SHOULD be the primary textual label by which this Contact is 792 normally displayed by the Service Provider when presenting it to 793 end-users. 795 name: The broken-out components and fully formatted version of the 796 contact's real name, as described in Section 7.3. 798 nickname: The casual way to address this Contact in real life, e.g. 799 "Bob" or "Bobby" instead of "Robert". This field SHOULD NOT be 800 used to represent a user's username (e.g. "jsmarr" or 801 "daveman692"); the latter should be represented by the 802 "preferredUsername" field. 804 published: The date this Contact was first added to the user's 805 address book or friends list (i.e. the creation date of this 806 entry). The value MUST be a valid xs:dateTime (e.g. 807 "2008-01-23T04:56:22Z"). 809 updated: The most recent date the details of this Contact were 810 updated (i.e. the modified date of this entry). The value MUST be 811 a valid xd:dateTime (e.g. "2008-01-23T04:56:22Z"). If this 812 Contact has never been modified since its initial creation, the 813 value MUST be the same as the value of "published". Note the 814 "updatedSince" Query Parameter described in Section 6.3 can be 815 used to select only contacts whose "updated" value is equal to or 816 more recent than a given xs:dateTime. This enables Consumers to 817 repeatedly access a user's data and only request newly added or 818 updated contacts since the last access time. 820 birthday: The birthday of this contact. The value MUST be a valid 821 xs:date (e.g. "1975-02-14". The year value MAY be set to "0000" 822 when the age of the Contact is private or the year is not 823 available. 825 anniversary: The wedding anniversary of this contact. The value 826 MUST be a valid xs:date (e.g. "1975-02-14". The year value MAY be 827 set to "0000" when the year is not available. 829 gender: The gender of this contact. Service Providers SHOULD return 830 one of the following Canonical Values, if appropriate: "male", 831 "female", or "undisclosed", and MAY return a different value if it 832 is not covered by one of these Canonical Values. 834 note: Notes about this contact, with an unspecified meaning or usage 835 (normally contact notes by the user about this contact). This 836 field MAY contain newlines. 838 preferredUsername: The preferred username of this contact on sites 839 that ask for a username (e.g. "jsmarr" or "daveman692"). This 840 field may be more useful for describing the owner (i.e. the value 841 when /@me/@self is requested) than the user's contacts, e.g. 842 Consumers MAY wish to use this value to pre-populate a username 843 for this user when signing up for a new service. 845 utcOffset: The offset from UTC of this Contact's current time zone, 846 as of the time this response was returned. The value MUST conform 847 to the offset portion of xs:dateTime, e.g. "-08:00". Note that 848 this value MAY change over time due to daylight saving time, and 849 is thus meant to signify only the current value of the user's 850 timezone offset. 852 connected: Boolean value indicating whether the user and this 853 Contact have established a bi-directionally asserted connection of 854 some kind on the Service Provider's service. The value MUST be 855 either "true" or "false". The value MUST be true if and only if 856 there is at least one value for the "relationship" field, 857 described below, and is thus intended as a summary value 858 indicating that some type of bi-directional relationship exists, 859 for Consumers that aren't interested in the specific nature of 860 that relationship. For traditional address books, in which a user 861 stores information about other contacts without their explicit 862 acknowledgment, or for services in which users choose to "follow" 863 other users without requiring mutual consent, this value will 864 always be false. 866 The following additional Singular Fields are defined, based on their 867 specification in OpenSocial [OpenSocial]: "aboutMe", "bodyType", 868 "currentLocation", "drinker", "ethnicity", "fashion", "happiestWhen", 869 "humor", "livingArrangement", "lookingFor", "profileSong", 870 "profileVideo", "relationshipStatus", "religion", "romance", 871 "scaredOf", "sexualOrientation", "smoker", and "status". 873 7.2.2. Plural Fields 875 Unless specified otherwise, all Plural Fields have the same three 876 standard sub-fields: 878 value: The primary value of this field, e.g. the actual e-mail 879 address, phone number, or URL. When specifying a "sortBy" field 880 in the Query Parameters for a Plural Field, the default meaning is 881 to sort based on this "value" sub-field. Each non-empty Plural 882 Field value MUST contain at least the value sub-field, but all 883 other sub-fields are optional. 885 type: The type of field for this instance, usually used to label the 886 preferred function of the given contact information. Unless 887 otherwise specified, this string value specifies Canonical Values 888 of "work", "home", and "other". 890 primary: A Boolean value indicating whether this instance of the 891 Plural Field is the primary or preferred value of for this field, 892 e.g. the preferred mailing address or primary e-mail address. 893 Service Providers MUST NOT mark more than one instance of the same 894 Plural Field as primary="true", and MAY choose not to mark any 895 fields as primary, if this information is not available. For 896 efficiency, Service Providers SHOULD NOT mark all non-primary 897 fields with primary="false", but should instead omit this sub- 898 field for all non-primary instances. 900 When returning Plural Fields, Service Providers SHOULD canonicalize 901 the value returned, if appropriate (e.g. for e-mail addresses and 902 URLs). Providers MAY return the same value more than once with 903 different types (e.g. the same e-mail address may used for work and 904 home), but SHOULD NOT return the same (type, value) combination more 905 than once per Plural Field, as this complicates processing by the 906 Consumer. 908 emails: E-mail address for this Contact. The value SHOULD be 909 canonicalized by the Service Provider, e.g. "joseph@plaxo.com" 910 instead of "joseph@PLAXO.COM". 912 urls: URL of a web page relating to this Contact. The value SHOULD 913 be canonicalized by the Service Provider, e.g. 914 "http://josephsmarr.com/about/" instead of 915 "JOSEPHSMARR.COM/about/". In addition to the standard Canonical 916 Values for "type", this field also defines the additional 917 Canonical Values "blog" and "profile". 919 phoneNumbers: Phone number for this Contact. No canonical value is 920 assumed here. In addition to the standard Canonical Values for 921 "type", this field also defines the additional Canonical Values 922 "mobile", "fax", and "pager". 924 ims: Instant messaging address for this Contact. No official 925 canonicalization rules exist for all instant messaging addresses, 926 but Service Providers SHOULD remove all whitespace and convert the 927 address to lowercase, if this is appropriate for the service this 928 IM address is used for. Instead of the standard Canonical Values 929 for "type", this field defines the following Canonical Values to 930 represent currently popular IM services: "aim", "gtalk", "icq", 931 "xmpp", "msn", "skype", "qq", and "yahoo". 933 photos: URL of a photo of this contact. The value SHOULD be a 934 canonicalized URL, and MUST point to an actual image file (e.g. a 935 GIF, JPEG, or PNG image file) rather than to a web page containing 936 an image. Service Providers MAY return the same image at 937 different sizes, though it is recognized that no standard for 938 describing images of various sizes currently exists. Note that 939 this field SHOULD NOT be used to send down arbitrary photos taken 940 by this user, but specifically profile photos of the contact 941 suitable for display when describing the contact. 943 tags: A user-defined category or label for this contact, e.g. 944 "favorite" or "web20". These values SHOULD be case-insensitive, 945 and there SHOULD NOT be multiple tags provided for a given contact 946 that differ only in case. Note that this field is a Simple Field, 947 meaning each instance consists only of a string value. 949 relationships: A bi-directionally asserted relationship type that 950 was established between the user and this contact by the Service 951 Provider. The value SHOULD conform to one of the XFN relationship 952 values (e.g. kin, friend, contact, etc.) if appropriate, but MAY 953 be an alternative value if needed. Note this field is a parallel 954 set of category labels to the "tags" field, but relationships MUST 955 have been bi-directionally confirmed, whereas tags are asserted by 956 the user without acknowledgment by this Contact. Note that this 957 field is a Simple Field, meaning each instance consists only of a 958 string value. 960 addresses: A physical mailing address for this Contact, as described 961 in Section 7.4. 963 organizations: A current or past organizational affiliation of this 964 Contact, as described in Section 7.5. 966 accounts: An online account held by this Contact, as described in 967 Section 7.6. 969 The following additional Plural Fields are defined, based on their 970 specification in OpenSocial: "activities", "books", "cars", 971 "children", "food", "heroes", "interests", "jobInterests", 972 "languages", "languagesSpoken", "movies", "music", "pets", 973 "politicalViews", "quotes", "sports", "turnOffs", "turnOns", and 974 "tvShows". 976 7.3. name Element 978 The components of the contact's real name. Providers MAY return just 979 the full name as a single string in the "formatted" sub-field, or 980 they MAY return just the individual component fields using the other 981 sub-fields, or they MAY return both. If both variants are returned, 982 they SHOULD be describing the same name, with the formatted name 983 indicating how the component fields should be combined. 985 formatted: The full name, including all middle names, titles, and 986 suffixes as appropriate, formatted for display (e.g. "Mr. Joseph 987 Robert Smarr, Esq."). This is the Primary Sub-Field for this 988 field, for the purposes of sorting and filtering. 990 familyName: The family name of this Contact, or "Last Name" in most 991 Western languages (e.g. "Smarr" given the full name "Mr. Joseph 992 Robert Smarr, Esq."). 994 givenName: The given name of this Contact, or "First Name" in most 995 Western languages (e.g. "Joseph" given the full name "Mr. Joseph 996 Robert Smarr, Esq."). 998 middleName: The middle name(s) of this Contact (e.g. "Robert" given 999 the full name "Mr. Joseph Robert Smarr, Esq."). 1001 honorificPrefix: The honorific prefix(es) of this Contact, or 1002 "Title" in most Western languages (e.g. "Mr." given the full name 1003 "Mr. Joseph Robert Smarr, Esq."). 1005 honorificSuffix: The honorifix suffix(es) of this Contact, or 1006 "Suffix" in most Western languages (e.g. "Esq." given the full 1007 name "Mr. Joseph Robert Smarr, Esq."). 1009 7.4. address Element 1011 The components of a physical mailing address. Service Providers MAY 1012 return just the full address as a single string in the "formatted" 1013 sub-field, or they MAY return just the individual component fields 1014 using the other sub-fields, or they MAY return both. If both 1015 variants are returned, they SHOULD be describing the same address, 1016 with the formatted address indicating how the component fields should 1017 be combined. 1019 formatted: The full mailing address, formatted for display or use 1020 with a mailing label. This field MAY contain newlines. This is 1021 the Primary Sub-Field for this field, for the purposes of sorting 1022 and filtering. 1024 streetAddress: The full street address component, which may include 1025 house number, street name, PO BOX, and multi-line extended street 1026 address information. This field MAY contain newlines. 1028 locality: The city or locality component. 1030 region: The state or region component. 1032 postalCode: The zipcode or postal code component. 1034 country: The country name component. 1036 7.5. organization Element 1038 Describes a current or past organizational affiliation of this 1039 contact. Service Providers that support only a single Company Name 1040 and Job Title field should represent them with a single 1041 "organization" element with "name" and "title" properties, 1042 respectively. 1044 name: The name of the organization (e.g. company, school, or other 1045 organization). This field MUST have a non-empty value for each 1046 organization returned. This is the Primary Sub-Field for this 1047 field, for the purposes of sorting and filtering. 1049 department: The department within this organization. 1051 title: The job title or role within this organization. 1053 type: The type of organization, with Canonical Values "job" and 1054 "school". 1056 startDate: The date this Contact joined this organization. This 1057 value SHOULD be a valid xs:date if possible, but MAY be an 1058 unformatted string, since it is recognized that this field is 1059 often presented as free-text. 1061 endDate: The date this Contact left this organization or the role 1062 specified by title within this organization. This value SHOULD be 1063 a valid xs:date if possible, but MAY be an unformatted string, 1064 since it is recognized that this field is often presented as free- 1065 text. 1067 location: The physical location of this organization. This may be a 1068 complete address, or an abbreviated location like "San Francisco". 1070 description: A textual description of the role this Contact played 1071 in this organization. This field MAY contain newlines. 1073 7.6. account Element 1075 Describes an account held by this Contact, which MAY be on the 1076 Service Provider's service, or MAY be on a different service. 1077 Consumers SHOULD NOT assume that this account has been verified by 1078 the Service Provider to actually belong to this Contact. For each 1079 account, the "domain" is the top-most authoritative domain for this 1080 account, e.g. "yahoo.com" or "reader.google.com", and MUST be non- 1081 empty. Each account must also contain a non-empty value for either 1082 "username" or "userid", and MAY contain both, in which case the two 1083 values MUST be for the same account. These accounts can be used to 1084 determine if a user on one service is also known to be the same 1085 person on a different service, to facilitate connecting to people the 1086 user already knows on different services. If Consumers want to turn 1087 these accounts into profile URLs, they can use an open-source library 1088 like [google-sgnodemapper]. 1090 domain: The top-most authoritative domain for this account, e.g. 1091 "twitter.com". This is the Primary Sub-Field for this field, for 1092 the purposes of sorting and filtering. 1094 username: An alphanumeric user name, usually chosen by the user, 1095 e.g. "jsmarr". 1097 userid: A user ID number, usually chosen automatically, and usually 1098 numeric but sometimes alphanumeric, e.g. "12345" or "1Z425A". 1100 8. IANA Considerations 1102 This memo includes no request to IANA at this time. [[Future drafts 1103 are likely to request registration for the XML and JSON content 1104 types.]] 1106 9. Security Considerations 1108 This memo abides by the security considerations of HTTP Basic Auth 1109 [RFC2617] and the OAuth protocol [OAuth Core 1.0]. 1111 Appendix A. Example 1113 Here is a sample request and response that illustrates much of 1114 Portable Contacts. For simplicity, authorization information is not 1115 shown in the request. 1117 Sample request (via HTTP GET): 1119 http://sample.site.org/path/to/api/@me/@all?startIndex=10 1120 &count=10&sortBy=displayName 1122 Sample response (JSON): 1124 { 1125 "startIndex": 10, 1126 "itemsPerPage": 10, 1127 "totalResults": 12, 1128 "entry": [ 1129 { 1130 "id": "123", 1131 "displayName": "Minimal Contact" 1132 }, 1133 { 1134 "id": "703887", 1135 "displayName": "Mork Hashimoto", 1136 "name": { 1137 "familyName": "Hashimoto", 1138 "givenName": "Mork" 1139 }, 1140 "birthday": "0000-01-16", 1141 "gender": "male", 1142 "drinker": "heavily", 1143 "tags": [ 1144 "plaxo guy" 1145 ], 1146 "emails": [ 1147 { 1148 "value": "mhashimoto-04@plaxo.com", 1149 "type": "work", 1150 "primary": "true" 1151 }, 1152 { 1153 "value": "mhashimoto-04@plaxo.com", 1154 "type": "home" 1155 }, 1156 { 1157 "value": "mhashimoto@plaxo.com", 1158 "type": "home" 1159 } 1160 ], 1161 "urls": [ 1162 { 1163 "value": "http://www.seeyellow.com", 1164 "type": "work" 1165 }, 1166 { 1167 "value": "http://www.angryalien.com", 1168 "type": "home" 1169 } 1170 ], 1171 "phoneNumbers": [ 1172 { 1173 "value": "KLONDIKE5", 1174 "type": "work" 1175 }, 1176 { 1177 "value": "650-123-4567", 1178 "type": "mobile" 1179 } 1180 ], 1181 "photos": [ 1182 { 1183 "value": "http://sample.site.org/photos/12345.jpg", 1184 "type": "thumbnail" 1185 } 1186 ], 1187 "ims": [ 1188 { 1189 "value": "plaxodev8", 1190 "type": "aim" 1191 } 1192 ], 1193 "addresses": [ 1194 { 1195 "type": "home", 1196 "streetAddress": "742 Evergreen Terrace\nSuite 123", 1197 "locality": "Springfield", 1198 "region": "VT", 1199 "postalCode": "12345", 1200 "country": "USA", 1201 "formatted": 1202 "742 Evergreen Terrace\nSuite 123\nSpringfield, VT 12345 USA" 1203 } 1204 ], 1205 "organizations": [ 1206 { 1207 "name": "Burns Worldwide", 1208 "title": "Head Bee Guy" 1210 } 1211 ], 1212 "accounts": [ 1213 { 1214 "domain": "plaxo.com", 1215 "userid": "2706" 1216 } 1217 ] 1218 } 1219 ] 1220 } 1222 Sample response (XML): 1224 1225 10 1226 10 1227 12 1228 1229 123 1230 Minimal Contact 1231 1232 1233 703887 1234 Mork Hashimoto 1235 1236 Hashimoto 1237 Mork 1238 1239 0000-01-16 1240 male 1241 heavily 1242 plaxo guy 1243 1244 mhashimoto-04@plaxo.com 1245 work 1246 true 1247 1248 1249 mhashimoto-04@plaxo.com 1250 home 1251 1252 1253 mhashimoto@plaxo.com 1254 home 1255 1256 1257 http://www.seeyellow.com 1258 work 1259 1260 1261 http://www.angryalien.com 1262 home 1263 1264 1265 KLONDIKE5 1266 work 1267 1268 1269 650-123-4567 1270 mobile 1271 1272 1273 http://sample.site.org/photos/12345.jpg 1274 thumbnail 1275 1276 1277 plaxodev8 1278 aim 1279 1280 1281 home 1282 1284 Springfield 1285 VT 1286 12345 1287 USA 1288 1291 1292 1293 Burns Worldwide 1294 Head Bee Guy 1295 1296 1297 plaxo.com 1298 2706 1299 1300 1301 1303 Appendix B. Compatibility with OpenSocial 1305 This version of the Portable Contacts specification is currently 1306 wire-compatible with the overlapping portion of the OpenSocial 1307 RESTful Protocol version 0.8.1 [OpenSocial]. Specifically, _any 1308 compliant OpenSocial RESTful Protocol 0.8.1 Provider is also a 1309 compliant Portable Contacts Provider_, because they are specified to 1310 use the same Authorization methods (OAuth), Additional Path 1311 Information, Query Parameters, and Contact Schema. The OpenSocial 1312 and Portable Contacts communities chose to wire-align our respective 1313 specs in order to maximize widespread adoption of a single API for 1314 accessing people data. 1316 It is our intention to maintain this compatibility going forward, so 1317 long as it is feasible, and so long as the changes required are 1318 compatible with the Goals and Approach of this spec. Although 1319 Portable Contacts is an independent spec, with a more limited scope 1320 than OpenSocial, any proposed changes to either this Portable 1321 Contacts spec or the OpenSocial RESTful Protocol should be considered 1322 in the context of both communities, and we should strive not to break 1323 compatibility unless it is truly necessary, e.g. if the goals of the 1324 two communities diverge significantly in the future. 1326 10. References 1328 10.1. Normative References 1330 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1331 Requirement Levels", BCP 14, RFC 2119, March 1997. 1333 [RFC2425] Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type 1334 for Directory Information", RFC 2425, September 1998. 1336 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1337 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1338 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1340 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1341 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1342 Authentication: Basic and Digest Access Authentication", 1343 RFC 2617, June 1999. 1345 10.2. Informative References 1347 [OAuth Core 1.0] 1348 OAuth, OCW., "OAuth Core 1.0". 1350 [OAuth Discovery] 1351 Eran Hammer-Lahav, E., "OAuth Discovery 1.0". 1353 [OpenSearch] 1354 Clinton, D., "OpenSearch 1.1". 1356 [OpenSocial] 1357 Panzer, J., "OpenSocial 0.8.1 RESTful Protocol 1358 Specification". 1360 [XRDS-Simple] 1361 Hammer-Lahav, E., "XRDS-Simple 1.0". 1363 [google-sgnodemapper] 1364 Fitzpatrick, B., "Social Graph Node Mapper". 1366 Author's Address 1368 Joseph Smarr 1369 Plaxo 1371 Email: joseph@plaxo.com 1372 URI: http://josephsmarr.com/ 1374 Full Copyright Statement 1376 Copyright (C) The IETF Trust (2008). 1378 This document is subject to the rights, licenses and restrictions 1379 contained in BCP 78, and except as set forth therein, the authors 1380 retain all their rights. 1382 This document and the information contained herein are provided on an 1383 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1384 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1385 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1386 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1387 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1388 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1390 Intellectual Property 1392 The IETF takes no position regarding the validity or scope of any 1393 Intellectual Property Rights or other rights that might be claimed to 1394 pertain to the implementation or use of the technology described in 1395 this document or the extent to which any license under such rights 1396 might or might not be available; nor does it represent that it has 1397 made any independent effort to identify any such rights. Information 1398 on the procedures with respect to rights in RFC documents can be 1399 found in BCP 78 and BCP 79. 1401 Copies of IPR disclosures made to the IETF Secretariat and any 1402 assurances of licenses to be made available, or the result of an 1403 attempt made to obtain a general license or permission for the use of 1404 such proprietary rights by implementers or users of this 1405 specification can be obtained from the IETF on-line IPR repository at 1406 http://www.ietf.org/ipr. 1408 The IETF invites any interested party to bring to its attention any 1409 copyrights, patents or patent applications, or other proprietary 1410 rights that may cover technology that may be required to implement 1411 this standard. Please address the information to the IETF at 1412 ietf-ipr@ietf.org.