(Contents of this doc will be have been added to the main Release Notes doc. Links will be fixed at that time.)
Primary focus of this version The server-to-server protocols are the primary focus of version 0.8.1. The Person schema has been aligned with the Portable Contacts effort, and an optional RPC proposal has been added.
OpenSocial specification changes- Server side API changes. Server to server functionality has been expanded with the addition of a [JSON RPC protocol http://link-to-rpc-protocol-spec],
which will allow for simpler batching of requests. To maintain naming
consistency, the RESTful API is now known as the RESTful protocol.
- OpenSocial IDs now allow "-", "_", and "." characters. OpenSocial IDs may now contain "-", "_", and "." in addition to alphanumeric characters.
- Aligned with Portable Contacts.
Incompatible changes
- RESTful protocol incompatibilities. The RESTful protocol has renamed or deleted many query and response fields. Please consult the list of [RESTful protocol changes #link-to-the-section-below] for a list of all of the RESTful changes.
RESTful protocol changes- Compatibility with PortableContacts. By implementing the RESTful protocol, a container now becomes technically compatible with the [PortableContacts http://portablecontacts.net/] specification. Many of the following changes were implemented to facilitate this compatibility:
- New format=xml response type. Requests will support the format=xml parameter. People requests must be made in either format=xml or format=json.
- Containers MUST implement random access pagination. Containers are now required to implement paging of results via the startIndex and itemsPerPage parameters.
- Removal of the link rel=next Collection field. This parameter has been removed from JSON Collection responses.
- Removal of the author Collection field. This parameter has been removed from JSON collection responses.
- Containers SHOULD support returning all contacts at once.
It should be possible to return all the requested contacts in a single
request, however containers may choose to limit the maximum items
returned per request for performance reasons.
- Default itemsPerPage behavior. It is up to each container to define the number of contacts returned when no itemsPerPage parameter is specified in a request.
- Changes to sorting parameters. The orderBy parameter has been renamed to sortBy. A new sortOrder parameter has been introduced, with values ascending and descending. The default value of sortOrder is ascending.
- New updatedSince query parameter. Queries may now specify that results only contain entries that have been updated in a specified interval.
- Responses indicate whether sorting and filtering have taken place. Since
sorting and filtering on arbitrary fields can be too expensive for a
container to support, responses now contain top-level response fields filtered, sorted, and updatedSince, to indicate whether the content in the response was filtered according to the original request.
- Ability to request deleted Person objects. Using a new @deleted selector and the updatedSince parameter, it is possible to retrieve all contacts that were deleted since the supplied date
- Person responses MUST contain at least the id and name fields. Containers must return at least a name and an id when returning Person data.
- A profile URL is a URL, too. The value returned in the profileUrl Person field MUST also be returned in the urls field, as a type=profile entry.
- New Person photos field. Person records now include a photos field, which will contain a list of entries with sub-fields url, type and primary. If the thumbnailUrl field is returned on a Person object, this url must also be present in the photos field, as a type=thumbnail entry.
- New Person ims field. Person records now include an ims field, which will contain a list of entries with sub-fields value, type, and primary. The type
values of "aim", "gtalk", "icq", "xmpp", "msn", "skype", "qq" and
"yahoo" are defined to match several commonly used services, although
new types may be defined as well.
- New Person accounts field. Person records now include an accounts
field, used to represent other services where the Person has accounts.
This field will contain a list of entries with sub-fields domain, userid, username, and primary.
- Plural Person fields get a primary sub-field. The emails, urls, ims, phoneNumbers, addresses, organizations, and photos
Person fields will recieve an additional primary sub-field which will
indicate which field in the list (if any) is the "primary value" of
that type.
- Combine the jobs and schools plural fields to organizations. Entries for jobs and schools will be combined into one array of Organization structures named organizations. The Organization structure will be extended with a type sub-field, with canonical values of "job" and "school".
- Plural Person fields standardize on a value field. The primary textual value of plural Person fields should be stored in a sub-field named value. This will require renaming emails.address, phoneNumbers.number, urls.address and all instances of the {Enum}.key field to {Enum}.value. The addresses, accounts, and organizations fields are complex and do not have the concept of a value field. For the purposes of sorting and filtering, the corresponding "primary" sub-fields on these fields will be addresses.formatted, accounts.domain, and organizations.name.
- The Person.gender field is now a string. Person records will now treat gender as a string field, with the canonical values of "male" and "female".
- Addresses no longer contain extendedAddress or poBox sub-fields. The extendedAddress and poBox Address subfields have been removed in favor of storing a complete (and potentially multi-line) address in the streetAddress sub-field.
- Rename unstructuredAddress to formatted. The unstructuredAddress sub-field of an Address is renamed to formatted.
- Rename dateOfBirth to birthday. The dateOfBirth Person field is renamed to birthday.
- Rename timeZone to utcOffset. The timeZone Person field is renamed to utcOffset.
- Definition of nickname. The nickname Person field is now defined as "the casual way to address this person in real life".
- Default set of Person fields is specified. If a Person request is missing the fields query parameter, the minimal set of fields that must be returned by default have been defined as id, name, and thumbnailUrl, to match the defaults for the JS API.
- Query for supportedFields. The RESTful protocol now defines the endpoints /people/@supportedFields and /activities/@supportedFields, which will return lists of the Person and Activity fields supported by the container.
- Removal of indexBy. The indexBy query parameter has been removed.
- The Activity.title field is now an HTML string. The Activity title field is now treated as a string that may contain HTML markup, instead of a complex data object.
- Rename unstructured to formatted. The unstructured Name field is renamed to formatted.
- New displayName field added. The displayName field is added as a required top-level Person field.
RPC protocol changes- Introducing the RPC Protocol. A new, optional [RPC protocol http://link-to-rpc-protocol-spec] has been introduced to simplify batching and complex server-to-server operations.
opensocial.* JavaScript changes - New opensocial.IdSpec.GroupId enum. This enum may be used to construct an IdSpec object, using either the values of opensocial.IdSpec.GroupId.FRIENDS and opensocial.IdSpec.GroupId.SELF.
- supportsField responses specified. The return values for opensocial.Environment.supportsField() calls have been defined as true when a container supports a field, and false otherwise.
gadgets.* JavaScript changes - No changes have been made to the gadgets.* JavaScript API.
Gadgets XML changes - Support for OAuth in the <Preload> element. The <Preload> element now supports the value of "oauth" for its authz attribute. If authz=oauth is specified, then the oauth_service_name, oauth_token_name, oauth_request_token, and oauth_request_token_secret attributes will be accepted. These attributes have the same semantics and defaults as their corresponding gadgets.io.makeRequest parameters.
|
