Gadgets REST

From VZ Developer Wiki
Jump to: navigation, search

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


OpenSocial REST API

Services

These sections define the core types that we support, their XRDS types, and their semantics. Unless otherwise specified, all HTTP operations are generally allowed for any URI endpoint.

Endpoints

Our possible endpoints are:

You can detect the right endpoint for the current call by the oauth_consumer_key parameter or by the user's ID.

Help.png

This tutorial will give you more examples or information on these features:
Lesson 12: Using the OpenSocial REST API

Client libraries

See Client_Libraries

Requests - General

These additional query parameters may be used with any URI of any service. The parameters startIndex and count are interpreted according to the OpenSearch spec.


count={count}
Requests page size for paged collection. If no parameter is specified we return 20 items to the collection.
filterBy={fieldname}
For a collection, return entries filtered by the given field.
filterOp={operation}
The operation to use when filtering a collection, defaults to "contains". Valid values are contains, equals, startsWith, and present.
filterValue={value}
The value to use when filtering a collection. For example, filterBy=name&filterOp=startsWith&filterValue=John will return all items whose name field starts with John. Johnny and John Doe would both be included.)
format={format}
Format desired; one of (atom, json, xml); default is json if not provided
fields={-join|,|field}
List of fields to include in representation or in the members of a collection. If no fields are provided we return aminimum set of fields. For people this is id, displayName, profileUrl and thumbnailUrl. @all is accepted to indicate returning all available fields.
sortBy={fieldname}
For a collection, return entries sorted by the given field.
sortOrder={order}
Can either be "ascending" or "descending", defaults to ascending. Used to sort objects in a collection.
startIndex={startIndex}
Index into a paged collection
callback={methodName}
If the callback parameter is specified and the output format is json, the server will respond with a JSONP response (see http://en.wikipedia.org/wiki/JSON#JSONP).

We do not support networkDistance and updatedSince filtering. However you can use all available fields to sort and filter data.

Operations

OpenSocial uses standard HTTP methods: GET to retrieve, PUT to update in place, POST to create new, and DELETE to remove. POST is special; it operates on collections and creates new activities, persons, or app data within those collections, and returns the base URI for the created resource in the Location: header, per AtomPub semantics.

Restricted clients, or clients behind restricted clients, which cannot use PUT or DELETE SHOULD translate PUT and DELETE to POST operations with an additional X-HTTP-Method-Override: header:

   POST /... HTTP/1.1
   ...
   X-HTTP-Method-Override: PUT

Groups

OpenSocial Groups are owned by people, and are used to tag or categorize people and their relationships. The RESTful API supports querying for the available groups for a given user. The groups are returned as a collection. Each group has a display name, an identifier which is unique within the groups owned by that person, and a URI link. We only support the groups @all and @friends which return the same subset of users connected with the current user, as well as the group @self to indicate that you want to access the user himself.

Responses - General

The structure of the response object returned from a successful request for the JSON or XML formats is as follows. The root element isresponse, which is shown explicitly as the root element in XML format, and is the anonymous root object returned when the format is json (i.e. in JSON, the response returned is the object value of the response node). The response node contains the following child nodes. Note that startIndex, itemsPerPage, and totalResults are based on OpenSearch.

  • startIndex: the index of the first result returned in this response, relative to the starting index of all results that would be returned if no startIndex had been requested. In general, this will be equal to the value requested by the startIndex, or 0 if no specific startIndex was requested.
  • itemsPerPage: the number of results returned per page in this response. In general, this will be equal to the count Query Parameter, but MAY be less if the Service Provider is unwilling to return as many results per page as requested, or if there are less than the requested number of results left to return when starting at the current startIndex. This field MUST be present if and only if a value for count is specified in the request.
  • totalResults: the total number of contacts that would be returned if there were no startIndex or count specified. This value tells the Consumer how many total results to expect, regardless of the current pagination being used, but taking into account the current filtering options in the request.
  • entry: an array of objects, one for each item matching the request, as defined in Section 7.2 (entry Element). For consistency of parsing, if the request could possibly return multiple items (as is normally the case), this value MUST always be an array of results, even if there happens to be 0 or 1 matching results. If the request is specifically for a single contact (e.g. because the request contains Additional Path Information like /@me/@all/{id} or /@me/@self), then entry MUST be an object containing the single item returned (i.e. "entry": [ { /* first item */ } ] and "entry": { /* only item */ } respectively).

Field Names

Each field is defined as either a Singular Field, in which case there can be at most one instance of that field per contact, or as a Plural Field, which case any number of instances of that field may be present per contact. Unless otherwise specified, all fields are optional and of type xs:string.

Examples

application/json representation:

{
   "startIndex" : 1
   "itemsPerPage" : 10
   "totalResults" : 100,
   "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
}

or, for only one item:

{
  "startIndex" : 1
  "itemsPerPage" : 10
  "totalResults" : 100,
  "entry" : {...only item...}
}

or, JSONP representation if the request had a callback parameter

methodName({
   "startIndex" : 1
   "itemsPerPage" : 10
   "totalResults" : 100,
   "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
})

xml representation:

<response>
   <startIndex> 1 </startIndex>
   <itemsPerPage> 10 <itemsPerPage>
   <totalResults> 100 <totalResults>
   <entry>...first item...</entry>
   <entry>...second item...</entry> 
      ...
</response>

or, for only one item:

<response>
   <startIndex> 1 </startIndex>
   <itemsPerPage> 10 <itemsPerPage>
   <totalResults> 100 <totalResults>
   <entry>...first item...<entry>
</response>

The atom format uses the JSON to Atom mapping rules described above and has a different base format than the XML:

application/atom+xml representation:

<feed xmlns="http://www.w3.org/2005/Atom" xmlos:osearch="http://a9.com/-/spec/opensearch/1.1">
  <author><uri>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</uri></author>
  <link rel="next" href="http://api.example.org/..." />
  <osearch:totalResults>100</osearch:totalResults>
  <osearch:startIndex>1</osearch:startIndex>
  <osearch:itemsPerPage>10</osearch:itemsPerPage>
  <entry>...first item...</entry>
  <entry>...second item...</entry>
  ...
</feed>

Request Authentication and Authorization

You can access public and private data using the OpenSocial REST API. If you want to access data, your client needs to authenticate first, using OAuth, and then provide credentials with requests. Every request for data must be accompanied by OAuth authentication parameters.

OAuth is an open standard authentication protocol that allows applications to make authorized and authenticated API calls. With OAuth, your application doesn't need access to the user's username and password; instead, the application obtains obtains an authentication token from the social network site that your application can use to act on the user's behalf.

Getting your Consumer Credentials

OAuth 1.0 Two Legged

When creating a gadget credentials for two-legged OAuth are added automatically and can be retrieved at http://www.studivz.net/GadgetDeveloper/GadgetOAuth/gadgetId or http://www.meinvz.net/GadgetDeveloper/GadgetOAuth/gadgetId

OAuth 1.0 Three Legged, OAuth 2.0

You can create your credentials at http://www.studivz.net/OAuth/Credentials or http://www.meinvz.net/OAuth/Credentials

Combining Two Legged and Three Legged access into one consumer

If you want to offer VZ users both a VZ-Login service along with a matching OpenSocial gadget on the VZ plattform you can, either create new VZ-Login consumer credentials from an existing Gadget (OAuth Keys->three legged OAuth->activate) or create a new gadget from existing existing VZ-Login credentials from the Services list.

This means that you will have the same internal consumer for both VZ-Login and your OpenSocial gadget.

When a user installs your gadget he automatically authorizes you for VZ-Login as well (by authorizing the shared consumer), which means that when he enters your site and logs in with his VZ credentials he will not have to "re-authorize" your VZ-Login consumer.

This of course works the other way around as well.

OAuth 1.0

We support the OAuth Version 1.0A in a two-legged OAuth and a three-legged OAuth Use Case. See OAuth for more information and possible endpoints.

OAuth 2.0

OAuth 2.0 simplifies the OAuth flow. You can use your credentials for both OAuth1 or OAuth2. See OAuth2 for details and the OAuth 2 endpoints.

HTTP Status Codes

Status code Description

400 BAD REQUEST
We return 400 BAD REQUEST under any one or more of the following conditions:
  • Invalid request URI
  • Invalid HTTP Header
  • Receiving an unsupported, nonstandard parameter
  • Receiving an invalid HTTP Message Body
401 UNAUTHORIZED
We return 401 UNAUTHORIZED when receiving a request for a protected resource and the request is either
  • Missing OAuth authorization credentials as described in OAuth Consumer Request 1.0, http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html.
  • OAuth authorization credentials are present, but the user identity is not authorized to access the protected resource. If the request already included authorization credentials, the 401 response indicates that the request has been refused for those credentials. A 401 response MUST include a WWW-Authenticate header field indicating the request MAY present an OAuth token for the container server's realm. Example: WWW-Authenticate: OAuth realm="http://sp.example.com/"
403 FORBIDDEN
The server understood the request but is refusing to fulfill it. Authorization will not help. The current authorization context does not allow the request.
404 NOT FOUND
The server has not found a resource (such as a feed or entry) that matches the request URI.
405 METHOD NOT ALLOWED
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.
409 CONFLICT
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required. Conflicts are most likely to occur in response to a PUT request. For example, this code can be used for a limit exceeded error as well as conflicting updates. See the error message for more information.
500 INTERNAL SERVER ERROR
Internal error. This is the default code that is used for all unrecognized errors.
501 NOT IMPLEMENTED
The request was valid but has not been implemented. We return 501 NOT IMPLEMENTED when receiving a request for an OPTIONAL/MAY feature that the we do not implement.