Gadgets REST People

From VZ Developer Wiki
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


Request

  • XRDS Type: http://ns.opensocial.org/2008/opensocial/people
  • guid : Container-globally-unique user identifier; identifies owner of the people data, or @me to indicate the requestor should be used
  • selector : One of
    • A user-defined local group name to select a group of contacts (a collection)
    • @self to select the person record for guid
    • @all or @friends to select all friends of the user (a collection)
  • pid : In the context of a collection selector, picks a single person record from that collection. The pid value MAY be relative to that collection.

People URI examples:

/people/{guid}/@all
Collection of all friends of user {guid},
/people/{guid}/@friends
Collection of all friends of user {guid}, equals @all
/people/{guid}/@all/{pid}
Individual person record for a specific person known to {guid}; shows {guid}'s view of {pid}.
/people/{guid}/@self
Profile record for user {guid}
/people/@me/@self
Profile record for requestor
/people/@supportedFields
Returns all of the fields that the container supports on people objects as an array in json and a repeated list in atom.

At the moment you can not add friendship connections or edit profile data.

Special filter for internal apps

Internal apps support the special hasApp filter. If this filter is set the people request only retrieves friends that have this application installed. Note: Since normal apps only can retrieve data of users that have installed the application this filter is only really usable for internal apps.

Response

All People Requests return a single person or a collection of people.

Person

A Person contains social network data about a single person. The same record is used for contacts/friends and for profiles.

See field names for a full list of available fields and their types.

A minimal Person example

application/json representation:

{

  "id" : "example.org:34KJDCSKJN2HHF0DW20394",
  "displayName" : "Janey",
  "name" : {"unstructured" : "Jane Doe"},
  "gender" : "female"
}

application/xml representation:

<person xmlns="http://ns.opensocial.org/2008/opensocial">
  <id></id>
  <displayName></displayName>
  <name>
    <unstructured>Jane Doe</unstructured>
  </name>
  <gender>female</gender>
</person>

application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="application/xml">
    <person xmlns="http://ns.opensocial.org/2008/opensocial">
      <name>
        <unstructured>Jane Doe</unstructured>
      </name>
      <gender>female</gender>
    </person>
  </content>
  <title/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author/>
  <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id>
</entry>

Note: The atom:summary element is the appropriate place to put a text or HTML representation of the structured data present in the content element, and the atom:title element is the appropriate place to copy a short descriptive name for the entry, such as name.unstructured. Servers MAY choose to add these or other fields to make their feeds more useful for generic aggregators or tools.

Each person returned includes the id and displayName fields with non-empty values, but all other fields are optional.

singular person fields

id
Unique identifier for the Person. Each Person returned MUST include a non-empty id value. This identifier is unique for all platforms.
displayName
The name of this Person, suitable for display to end-users. Each Person returned MUST include a non-emptydisplayName value. The name SHOULD be the full name of the Person being described if known (e.g. Cassandra Doll or Mrs. Cassandra Lynn Doll, Esq.), but MAY be a username or handle, if that is all that is available (e.g. doll). The value provided SHOULD be the primary textual label by which this Person is normally displayed by the Service Provider when presenting it to end-users.
name
The broken-out components and fully formatted version of the person's real name, as described in Section name Element.
published
The date this Person was first added to the user's address book or friends list (i.e. the creation date of this entry). The value MUST be a valid xs:dateTime (e.g. 2008-01-23T04:56:22Z).
updated
The most recent date the details of this Persont were updated (i.e. the modified date of this entry). The value MUST be a valid xd:dateTime (e.g. 2008-01-23T04:56:22Z). If this Person has never been modified since its initial creation, the value MUST be the same as the value of published. Note the updatedSince Query Parameter can be used to select only people whose updated value is equal to or more recent than a given xs:dateTime. This enables Consumers to repeatedly access a user's data and only request newly added or updated contacts since the last access time.
birthday
The birthday of this person. The value MUST be a valid xs:date (e.g. 1975-02-14. The year value MAY be set to0000 when the age of the Person is private or the year is not available.
gender
The gender of this person. Service Providers SHOULD return one of the following Canonical Values, if appropriate:male, female, or undisclosed, and MAY return a different value if it is not covered by one of these Canonical Values.
utcOffset
The offset from UTC of this Person's current time zone, as of the time this response was returned. The value MUST conform to the offset portion of xs:dateTime, e.g. -08:00. Note that this value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.
connected
Boolean value indicating whether the user and this Person have established a bi-directionally asserted connection of some kind on the Service Provider's service. The value MUST be either true or false. The value MUST be true if and only if there is at least one value for the relationship field, described below, and is thus intended as a summary value indicating that some type of bi-directional relationship exists, for Consumers that aren't interested in the specific nature of that relationship. For traditional address books, in which a user stores information about other contacts without their explicit acknowledgment, or for services in which users choose to "follow" other users without requiring mutual consent, this value will always be false.
platform
name of platform where the current user is registered (Svz; studiVZ, Avz: meinVZ, Pvz: schülerVZ)
lastLogin
only for internal apps

plural person fields

Unless specified otherwise, all Plural Fields have the same three standard sub-fields:

value
The primary value of this field, e.g. the actual e-mail address, phone number, or URL. When specifying a sortByfield in the Query Parameters for a Plural Field, the default meaning is to sort based on this value sub-field. Each non-empty Plural Field value MUST contain at least the value sub-field, but all other sub-fields are optional.
type
The type of field for this instance, usually used to label the preferred function of the given contact information. Unless otherwise specified, this string value specifies Canonical Values of work, home, and other.
primary
A Boolean value indicating whether this instance of the Plural Field is the primary or preferred value of for this field, e.g. the preferred mailing address or primary e-mail address. Service Providers MUST NOT mark more than one instance of the same Plural Field as primary="true", and MAY choose not to mark any fields as primary, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-primary fields with primary="false", but should instead omit this sub-field for all non-primary instances.

When returning Plural Fields, Service Providers SHOULD canonicalize the value returned, if appropriate (e.g. for e-mail addresses and URLs). Providers MAY return the same value more than once with different types (e.g. the same e-mail address may used for work and home), but SHOULD NOT return the same (type, value) combination more than once per Plural Field, as this complicates processing by the Consumer.

emails
E-mail address for this Person. The value SHOULD be canonicalized by the Service Provider, e.g.joseph@plaxo.com instead of joseph@PLAXO.COM.
photos
URL of a photo of this person. The value SHOULD be a canonicalized URL, and MUST point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a web page containing an image. Service Providers MAY return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists. Note that this field SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.
addresses
A physical mailing address for this Person, as described in Section 11.1.4 (address Element).

The following additional Plural Fields are defined, based on their specification in OpenSocial: politicalViews.

name element

The components of the person's real name. Providers MAY return just the full name as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component fields should be combined.

familyName
The family name of this Person, or "Last Name" in most Western languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr, Esq.).
givenName
The given name of this Person, or "First Name" in most Western languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr, Esq.).

address element

The components of a physical mailing address. Service Providers MAY return just the full address as a single string in the formattedsub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields should be combined.

streetAddress
The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.
locality
The city or locality component.
postalCode
The zipcode or postal code component.
country
The country name component.