OpenSocial Core API Server Specification 2.5.1opensocial-and-gadgets-spec@googlegroups.comThis document describes a method for making information
and services programatically available on the internet.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC2119.An implementation is not compliant if it fails to satisfy one or more of
the MUST or REQUIRED level requirements for the protocols it
implements.Domain name examples use
.The grammatical rules in this document are to be interpreted as
described in . The following constructs are introduced in this document to augment
RFC2234:Elements enclosed in braces (squiggly brackets) are treated as a
single, UNORDERED element. Its contents may occur in any order. Hence:
{elem foo} bar
would match (elem foo bar) and (foo elem bar).NOTE: Specifying alternatives is quite different from specifying set
grouping. Alternatives indicate the matching of exactly one (sub-)rule
out of the total grouping. The set mechanism indicates the matching of a
string which contains all of the elements within the group; however the
elements may occur in any order.A construct "#" is defined, similar to "*", for
defining lists of elements. The full form is "<n>#<m>element"
indicating at least <n> and at most <m> elements, each
separated by one or more commas (",") and OPTIONAL linear white space
(LWS). This makes the usual form of lists very easy; a rule such as
( *LWS element *( *LWS "," *LWS element ))
can be shown as
1#element
Wherever this construct is used, null elements are allowed, but do
not contribute to the count of elements present. That is, "(element), ,
(element) " is permitted, but counts as only two elements. Therefore,
where at least one element is required, at least one non-null element MUST
be present. Default values are 0 and infinity so that "#element" allows
any number, including zero; "1#element" requires at least one; and
"1#2element" allows one or two.A construct "&" is defined, similar to "#",
which uses an ampersand (&) instead of commas, and MUST NOT include
linear white space between elements.The grammar described by this specification is
word-based. Except where noted otherwise, linear white space (LWS) can be
included between any two adjacent words (token or quoted-string), and
between adjacent words and separators, without changing the interpretation
of a field. At least one delimiter (LWS and/or separators) MUST exist
between any two tokens, since they would otherwise be interpreted as a
single token.The following rules are used throughout this specification to describe
basic parsing constructs. The US-ASCII coded character set is defined by
CHAR =
UPALPHA =
LOALPHA =
ALPHA = UPALPHA / LOALPHA
DIGIT =
CTL =
CR =
LF =
SP =
HT =
<"> =
CRLF = CR LF
LWS = [CRLF] 1*( SP / HT )
TEXT =
COMMA =
]]>
OpenSocial defines REST and RPC protocols to allow remote clients access to server side data. The data formats are independent of the protocols used in requests and common data types and formats are described in the Core Data Specification. Common data types for social applications are documented in the Social Data Specification.The REST protocol defines a language and platform neutral protocol for clients to
interact with OpenSocial container servers outside of gadgets on a web page.
As a protocol, it is intended to be reasonably easy to implement in any
language and on any platform. It should also be usable across a range of
clients, from gadgets operating within a web page to servers communicating
to synchronize data about a user.API Servers MUST support the REST protocol.The protocol operates primarily in terms of resources and operations on
them. It is defined on top of the HTTP protocol, and uses the standard HTTP
methods (GET, POST, PUT, DELETE, etc.) to retrieve and change server
state.No single data representation is ideal for every client. This protocol
defines representations for each resource in three widely supported formats,
JSON, XML, and
Atom /
AtomPub, using a set of generic mapping rules.
The mapping rules allow a server to write to a single interface rather than
implementing the protocol three times.Support for the ATOM format is being deprecated in the OpenSocial 2.0 release. Consumers should start migrating to using JSON or XML representations.OpenSocial container servers are free to define additional
representations but MUST support at least the JSON and Atom formats for all
resources and XML for the people calls. XML MAY be supported for the rest of
the resources.Most operations consist of retrieving (GET), updating (PUT), creating (POST or
PUT), or destroying (DELETE) these resources. It also specifies an optional
partial update feature which avoids sending large resources over the wire to
update just one field.A REST request uses the following format:REST-Request = REST-HTTP-Method SP REST-Request-URI SP <any valid HTTP version identifier> CRLF
{
"HOST: " <any valid HTTP host> CRLF
[ "Authorization: " Auth-Token CRLF ]
[ "Content-Type: " Content-Type CRLF ]
[ *(<a valid HTTP header not defined above> CRLF) ]
}
CRLF
[ REST-Request-Payload ]
For example, here is a REST request to retrieve information about a
user:
GET /api/people/@me/@self?fields=name HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
Each REST resource defined in this document may specify the exact
semantics of each method, but generally, "GET" is associated with
retrieving a resource, "POST" is associated with creating a resource,
"PUT" is associated with updating a resource, and "DELETE" is associated
with deleting a resource.The following HTTP methods may be used for REST requests:REST-HTTP-Method = "GET" / "POST" / "PUT" / "DELETE"
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: Servers SHOULD respond to POST+X-HTTP-Method-Override as if the
content of the header were the actual operation sent.Note that OpenSocial
does not support cross-domain JSONP (GET with callback), but servers MAY
offer this as an extension. It is RECOMMENDED that such servers implement
appropriate security and authorization controls.The request URI is composed from the base path, a URI fragment, and optional query parameters.REST-Request-URI = REST-Base-PathREST-URI-Fragment ["?" REST-Query-Parameters]
An OpenSocial REST server may choose to expose their REST endpoints in
a "namespaced" way through use of a path. For example, the REST resource
of "http://www.example.com/apis/people" would have a REST base path of
"/apis", while "http://www.example.com/apis/opensocial-1.0/people" would
correspond with the REST base path of "/apis/opensocial-1.0".REST-Base-Path = String
The URI fragment defines the exact resource that a request is targeting. Each service defines the format and possible values for the URI fragment based on the resources the service exposes.REST-URI-Fragment = String
Each service type defines an associated partial URI format. The base URI
for each service is found in the URI element associated with the service in
the discovery document. Each service type accepts parameters via the URL
path. Definitions are of the form:Parameters must be filled in using left to right ordering. If a
positional pattern is missing, no parameters to the right of that parameter
may be filled in. For example, if the preceding pattern was used and only
the value of the a parameter was known and set to @me, the complete URL
would be expressed as: Additional parameters for a REST request MAY be passed via the
querystring portion of the request URI.REST-Query-Parameters = &ENCODE-REST-PARAMETER(k,v)
This specification defines a function ENCODE-REST-PARAMETER, which
is an alias for encoding a key/value pair. The PCT-ENCODE function
is described in section 2.1 of .
ENCODE-REST-PARAMETER(k,v) = PCT-ENCODE(k) "=" PCT-ENCODE(FLATTEN(v))
The FLATTEN function is also defined in this spec, and behaves in
the following manner:If the argument supplied is an array of strings or numbers, the
string representation of each array element is returned, with each element
separated by a COMMA.If the argument supplied is a string or a number, the string
representation of the argument is returned.The behavior of FLATTEN for input not explicitly covered here is
undefined. This includes associative arrays, or nested arrays.Here is an example of a REST request URL with query parameters. Note that the fields parameter demonstrates a flattened array:
http://www.example.com/opensocial/rest/people/@me/@self?fields=name,gender&format=json
A REST request MAY carry a payload, such as an object to create on the server. Each service defines which requests support a payload and the format of the payload.A REST response uses the following format:
HTTP/1.x HTTP-Status-Code
[ "Content-Type: " Content-Type ]
[ REST-Response-Payload ]
A REST request MAY contain a payload. Each service method defines the object that is included as the Return-Object. The payload uses the following format:REST-Response-Payload = [ REST-XML-Response-Payload | REST-JSON-Response-Payload ]
REST-XML-Response-Payload = "<response xmlns='http://ns.opensocial.org/2008/opensocial'>"
Return-Object
"</response>"
REST-JSON-Response-Payload = Return-Object / (<"> "error" <"> ":" RPC-Error)
DiscussionThe RPC protocol supports
the same data and operations as the RESTful API in a form that is more
natural for the JSON data format. Any batch of RPCs should be
programatically convertible to a sequence or batch of RESTful calls and
maintain the same semantics, any exception to this will be called out
explicitly.API Servers MAY support the RPC protocol.The RPC protocol shares the following with the RESTful protocol:The JSON/XML format of the OpenSocial data types such as Person, Activity,
Group, AppData are identical.HTTP status codes are used to represent common error cases where
applicable. is supported for authentication and
authorization in addition to other authorization schemes a container may
choose to support. A single OAuth token can be used for a batch of
operations or each operation can specify its own OAuth token.Concurrency control is optional.The RPC protocol differs from the RESTful protocol in the following ways:Conforms to the specificationAll structural elements in the protocol are represented using the JSON
or XML notation.Batch support is required.HTTP is used primarily as a transport and not to indicate the semantics
of the request.Automated discovery happens in two steps. XRDS can be used to discover
the RPC endpoint. The service can then be introspected by executing a request to the system.listMethods method to discover the list of available services and
operations using conventions defined by XML-RPC Introspection. In general it is expected
that a large percentage of consumers will bypass automated discovery and
rely on simply hardcoding references to the endpoints of various popular
containers.Containers MUST give access to the RPC services using a URL addressing
scheme to invoke a single RPC via HTTP GET. This encoding can also be used
to support RPC execution via form posts including file-uploads as parameters
to RPCs. It is recommended that only services that are idempotent are
exported in this manner. Containers MUST use the following canonical
transformation between the RPC structure and its URL encoding:The RPC method is defined by the 'method' query parameterThe RPC id is defined by the 'id' query parameterAll other query parameters are assumed to belong to the RPC params
element and are encoded from JSON using <field path dot
notation>=<scalar value> | <comma separated array of
scalars>. When a field represents an array of non-scalars then elements
of the array are identified by enclosing the index in parenthesis. Strings
which match [0-9]+ MUST be single-quoted, Strings which match [A-Za-z_]+
MUST be unquoted, all other strings retain their original quoting.The following provides some examples of mapping JSON objects to URL Parameters:JSON ObjectURL Parameter{ "field" : "value" }field=value{ "field" : [1,2,3,4,5]}field=1,2,3,4,5{ "field" : "12" }field='12'{ "field" :
[identifier,anotheridentifier]}field=identifier,anotheridentifier{ "field" : ["value","another value"]}field=value,"another
value"{ "field" : ['value','another value']}field=value,'another
value'{ "field" : { "nested" : "value" }}field.nested=value{ "field" : [{ "nested1" : "value1" }, { "nested2" : "value2"
}]}field(0).nested1=value1&field(1).nested2=value2For example, given the following RPC-Request-Payload:
{ "method" : "people.get", "id" : "myfriends", "params": {"userId" : "@me", "groupId" : "@friends" } }
The corresponding URL is:
http://api.example.org/rpc?method=people.get&id=myfriends¶ms.userId=@me¶ms.groupId=@friends
In situations where containers support the
URL Addressing scheme to perform an RPC
the container MAY return arbitrary content types in the response other than
application/json. The system.methodHelp operation relies on this to provide
browseable documentation.An RPC request uses the following format:
RPC-Request = "POST /" RPC-Base-URL " HTTP/1.1"
"HOST" <any valid HTTP host>
"Authorization: " Auth-Token
"Content-Type: " Content-TypeRPC-Request-PayloadFor example, here is a RPC request to retrieve information about a
user:
POST /rpc HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
{
"method" : "people.get",
"id" : "myself"
"params" : {
"userId" : "@me",
"groupId" : "@self"
}
}
The RPC Base URL is defined in the XRDS file.RPC requests MAY batch multiple procedure calls into a single HTTP
request. Therefore, the payload of an RPC request can container a JSON
array of procedure calls, or a single procedure call:RPC-Request-Payload = RPC-Batch-Payload / RPC-Single-Payload
RPC-Batch-Payload = "[" #RPC-Single-Payload "]"
RPC-Single-Payload = "{"
<"> "method" <"> ":" <"> RPC-Method <"> ","
<"> "id" <"> ":" <"> Request-ID <"> ","
[ <"> "params" <"> ":" RPC-Request-Parameters ]
"}"
Note that the "json-rpc" property defined in JSON-RPC is not passed in the request but requests MUST be interpreted as if "json-rpc" : "2.0" was supplied.If a method call has no parameters, or only default values are required, the "params" field can be omitted completely.Here is an example of a RPC request with a batch of procedure calls in
the payload:
POST /rpc HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
[
{
"method" : "people.get",
"id" : "myself",
"params" : {
"userId" : "@me",
"groupId" : "@self"
}
},
{
"method" : "people.get",
"id" : "myfriends",
"params" : {
"userId" : "@me",
"groupId" : "@friends"
}
}
]
Note that multiple authorization tokens MAY be used in a single batch request. The following example contains an authorization token as an HTTP header in the request, which is overridden by an authorization token provided in the 'auth' property in the second request object of the batch. In this example, assume that Alice doesn't have access to Bob's profile, so her authorization token is not sufficient to access his information. The client making the request has an authorization token for Bob's profile, so the client can include this token to retrieve his information as well. For more information on authentication and authorization, see Security.
POST /rpc HTTP/1.1
Host: api.example.org
Authorization: <1st Auth token>
Content-Type: application/json
[
{
"method" : "people.get",
"id" : "profileOfAlice"
"params: {
"userId" : "09737549474",
}
},
{
"method" : "people.get",
"id" : "profileOfBob",
"params: {
"userId" : "34906734059",
"auth" : "<2nd Auth token>"
}
}
]
The value of the "method" field in an OpenSocial RPC request uses a
format of "<service-name>.<operation>". <service-name> is
a string [A-Za-z0-9_]+ that identifies one of the services listed in
[Services] and <operation> is a string [A-Za-z0-9_]+ that identifies
an operation supported by that service.RPC-Method = <"> Service-Name "." Method-Name <">
Service-Name = String
Method-Name = String
All OpenSocial services MUST expose a "get" operation. Operations with the names get, create, update and delete should map to the HTTP equivalent operations in the RESTful protocol of
GET, PUT, POST & DELETE.Available methods can be determined by calling the
system.listMethods method.Parameters can be passed to RPC methods in the request payload as a
JSON object as described in Appropriate values for RPC request parameters can be determined by
calling the
system.methodSignatures method.Here is an example of an RPC request payload with procedure-specific
parameters (userId, groupId) and standard OpenSocial parameters:
{
"method" : "people.get",
"id" : "myself"
"params" : {
"userId" : "@me",
"groupId" : "@self",
"fields" : "name, gender",
"format" : "json"
}
}This specification defines a function ENCODE-RPC-PARAMETER which is
an alias for the JSON encoding process. This function takes a key and
value as arguments, where the key must be a string, and the value must
have a valid JSON encoding.ENCODE-RPC-PARAMETER(k,v) = "{" <"> k <"> ":" JSON-ENCODE(v) "}")An RPC response uses the following format:
HTTP/1.x 207 Multi-Status
"Content-Type: " Content-TypeRPC-Response-PayloadRPC responses MAY contain results from multiple procedure calls, if
the corresponding HTTP request contained a
RPC-Batch-Payload. The batch response elements MUST be returned in the same order
as the corresponding batch request elements and the "id" property of the corresponding
request in the batch request MUST be carried over to the response. If processing of the entire batch fails, as opposed to a single request within the batch, then the returned value is a single
RPC-Error object with the appropriate error message and
code.The response payload for a single procedure call MUST contain an 'id'
property to correlate the response with a request. On success, the
payload MUST contain a 'result' property. On failure, the payload MUST contain an 'error'
property. Each service method defines the object that is included as the Return-Object.RPC-Response-Payload = RPC-Batch-Payload / RPC-Single-Payload
RPC-Batch-Payload = RPC-Error / ("[" #RPC-Single-Payload"]")
RPC-Single-Payload = "{"
<"> "id" <"> ":" <"> Request-ID <"> ","
( (<"> "result" <"> ":" <Return-Object>) / (<"> "error" <"> ":" RPC-Error) )
"}"
The following examples illustrate how success and failure are
represented in responses to batch requests.
Batch successful, all procedure calls successful:
[
{
"id" : "myself",
"result" : { ... }
},
{
"id" : "myfriends",
"result" : { ... }
}
]
Batch successful, some procedure calls successful while some fail:
[
{
"id" : "myself",
"result" : { ... }
},
{
"id" : "myfriends",
"error" : { ... }
}
]
Batch successful, all procedure calls fail:
[
{
"id" : "myself",
"error" : { ... }
},
{
"id" : "myfriends",
"error" : { ... }
}
]
Batch fails:
{
"error" : { ... }
}
An error object MUST contain a 'code' property to indicate the actual
error that occurred and MAY contain a 'message' property describing the
error. Additional information may be returned in the 'data' property, as
defined by the procedure.
RPC-Error = "{"
[ <"> "message" <"> ":" <"> string <"> "," ]
[ <"> "data" <"> ":" <any JSON object> "," ]
<"> "code" <"> ":" integer ","
"}"
A common set of error codes are used to represent failure modes that
apply generally to operations and so are reserved for use by this
specification.CodeMeaning-32700 (Parse error)Invalid JSON. An error occurred on the server while parsing the JSON
text.-32600 (Invalid Request)The received JSON not a valid JSON-RPC or batch of JSON-RPCs.-32601 (Method not found)The requested remote-procedure does not exist / is not available.-32602 (Invalid params)Invalid method parameters.-32603 (Internal server error)Internal server error.-32099..-32000Reserved for implementation-defined server-errors.401 (Unauthorized)Access token does not grant access to the resource,404 (Not Found)The requested resource was not found.409 (Conflict)The requested update conflicts with a prior change.0-1000Reserved for future use by this specification.Here is an example of an unsuccessful RPC response payload:
{
"id" : "myself"
"error" : {
"code" : 401
"message" : "The authorization token does not provide access to the requested resource."
}
}
OpenSocial Containers MUST support TLS 2.0 / SSL connections for sensitive data
since OAuth on its own does not provide encryption or message body integrity checking.
Note that TLS 2.0/SSL is required with many scenarios in the OAuth 2.0 specification.Core Gadget Servers MUST support Open Authorization 1.0a
but SHOULD use appropriate policies to determine which operations are allowed on a per-consumer and
per-user basis.When OAuth 1.0a is used for authorization on a single RPC, the OAuth signature
uses the URL Addressing representation of the
request without the authorization parameter, in order to calculate the signature base string.DiscussionCore Gadget Servers MUST support the authorization server, resource server and client roles
defined in section 1.1 of the Open Authorization 2.0 specification .A Core Gadget Server MUST provide authorization, token issuance and resource access endpoints per the OAuth 2
specification.
A Core Gadget Server MUST implement the authorization code and client credential types described in section 4 of the
Open Authorization 2.0 specification. Core Gadget Servers SHOULD implement the implicit grant type.
Core Gadget Servers MAY implement the refresh token pattern described
in section 1.5 of the OAuth 2.0 specification.For 2 party (client credential) OAuth requests, if a Core Gadget Server has a user identifier
and wishes to indicate that the
operation is being done on behalf of that particular user, it SHOULD provide
the OAuth extension parameter xoauth_requestor_id along with the OAuth
parameters as a query fragment. Often times, the value for the xoauth_reqeustor_id
will be set to the e-mail address of the
user, on who's behalf the Core Gadget Server is making the call.
Core Gadget Servers SHOULD only provide the xoauth_requestor_id if the user has given prior
consent to the operation or class of operations being done on their behalf.
Core Gadget Servers MUST either honor the parameter or ignore it as if it were not
provided.OpenSocial Containers may wish to restrict requests from unknown clients and require gadget registration,
in order to mitigate risk. OpenSocial Containers SHOULD document how to register a gadget with the OpenSocial
Container in order to obtain a client identifier and client secret. This is typically done through a web page,
although the exact method is left to the specific implementation.Note that per the security considerations
mentioned in the OAuth 2.0 specification, client secrets should not be issued to untrusted clients.DiscussionOpenSocial Containers SHOULD document how to store client identifiers and client secrets on the server in order for
a gadget running locally to access remote data in another server.OpenSocial Containers SHOULD document how the OpenSocial Container handles redirection when authenticating
a user and obtaining authorization for a gadget. Note that this is a potential vector for phishing if the
user is required to enter their credentials. Normally, for three-party OAuth exchanges, the OpenSocial
Container will provide a web page
to collect authentication and scoped authorization information, although the exact method is left to the
specific implementation.OpenSocial Containers SHOULD base their security decisions on the type of client in use;
a generally available desktop client, for example, cannot effectively protect a client secret that
is installed with each client (implicit grant). The security of communications with a two-party partner
service, on the other hand, is dependent on the effectiveness of that service's security procedures
(client credential grant). The security of communications with a three party service, involving a
registered server, a client/gadget and the OpenSocial Container, should follow the security guidelines
outlined in the OAuth 2.0 security considerations document (authorization grant).OpenSocial Containers SHOULD provide an ability to scope the authorization to data as narrowly as
possible (e.g., allow reading but not writing if a client only performs reads).DiscussionOpenSocial Containers SHOULD issue access tokens with short expiration times to limit the scope
of security breaches due to stolen access tokens. The token expiration policy is left to the
specific implementation and may vary depending on the client requesting the token.
Expiration times of 1 hour or less, and tokens with limited scope may be used with less
trusted clients while expiration times of several hours and tokens with increased scope may be
used for more trusted clients. An OpenSocial Container SHOULD document (at least for administrators)
how to configure token scopes and expiration times if these values are configurable.Each API call from a gadget to the Core Gadget Server has a request context that usually includes
authentication and authorization information. Typically, the context
information includes the requester id (the user initiating the request) and
app Id (the application, or whatever is acting as the user's agent). It may
include other core container-specific information. The requesting application
and user may be implied through the OAuth tokens, or may be provided explicitly
in the xoauth_requestor_id optional parameter. Request contexts can also
include things such as cookies, URI parmaters, client SSL certificates and
other information.An OpenSocial Container may accept
requests with no authentication or authorization information
for public data. A container may provide a public version (e.g., of a
profile) if no authorization information is provided.Note that the data provided for a given RESTful URI MAY vary per
requestor or application. The data returned from a resource URI is "the
view of the information available to the current requestor/application combination".In the case where no information is available due to lack of authorization,
an HTTP 401 Unauthorized response SHOULD be returned to the client. In the
case where at least some view of the information is available, it SHOULD be
returned using a 200 status, with a standard OAuth WWW-Authenticate: header
indicating that additional information may be available when using a
different authorization context.DiscussionContent Upload is a generic mechanism to allow for a standard way to
upload content. This mechanism MAY be used to upload to an
existing Album, MediaItem endpoint, or where appropriate. In most scenarios an uploaded
content is associated with creation of an entity. Upload of content
routinely causes the creation of the entity. For example, uploading a
photo causes the container to create a new media item. The application can
then update that MediaItem and set attributes via a second request at some
later time. The requests look like:
Step 1: Upload PhotoStep 2: Update Photo attributes (title, description, etc.)The two step request process is illustrated below.Step 1: Upload the image in the album.
Step 2: PUT MediaItem details to MediaItem (id:223344) Note: response includes "caption" in addition to "title".
Caption is being deprecated in the 1.0 data format and will be removed
entirely in a future version of the spec.
The response indicates that the media item was updated.The shortcut upload mechanism is OPTIONAL. This two step process shown
above can be merged into one by a single POST request with the content
type set to the item being uploaded. The POST URL can optionally pass the
attributes. The Accept-type indicates the format of the response expected.
A container MAY choose to support file uploads from browsers to the RPC
endpoint and have the uploaded files be passed as parameters to the RPC.
This is achieved by browsers posting a form which contains the files to the
endpoint and including a form-parameter called "request" which contains the
form-encoded RPC request. The form input element names for the uploaded
files will be bound to the corresponding parameter names on execution.A multipart form-data request mechanism ("Content-Type:
multipart/form-data") enables upload of content. Such a request has the
POST body segmented into several sections (fields) with each field
identified by a name. The field name "request" is reserved and contains
request operation details (same as the contents on the POST body in the
vanilla POST operation).The fields with any other name contain content to be uploaded to the
OpenSocial container. To allow batching and multiple file uploads in a
single call, multiple fields (identified with unique field names) are
allowed. The OpenSocial request can refer to the content being uploaded by
setting the URL to "@field:<fieldname>". The container may host the
uploaded file and replace the URL field with a fully qualified URL for
future access.For a successful upload, the response code of the request will be
associated with the response code of the action request on the resource.
However, in case of a failure due to a file size exceeding limits, an error
code of 413 ("Request Entity Too Large") MUST be returned. The requested
action associated with the file upload MUST NOT be executed.A string identifying a request.A string used to authenticate a request.A string used to identify the type of content in a request or response.The actual content included in the response. Each service method defines the object that is included as the Return-Object.A collection of keys that identify resources that should have their cached version refreshed. Keys can either be URLs or IDs of objects to be refreshed.Keys that refer to URLs MUST include a protocol prefix (e.g. 'http://') so
they can be distinguished from ids. Each request accepts a repeated group
of keys.Invalidation-Key-List = "{"
<"> "invalidationKeys" <"> ":" "[" #Invalidation-Key "]"
"}"
Invalidation-Key = <any valid URL> / Object-IdStatus CodeDescription400 BAD REQUESTOpenSocial application servers MUST return 400 BAD REQUEST
under any one or more of the following conditions:
Invalid request URIInvalid HTTP HeaderReceiving an unsupported, nonstandard parameterA parameter is repeatedReceiving an invalid HTTP Message Body401 UNAUTHORIZED
OpenSocial container servers MUST return 401 UNAUTHORIZED
when receiving an OAuth request for a protected resource and the request is either
Missing OAuth authorization credentials as described in
for OAuth 1.0a or in for OAuth 2.0 requests. 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/"Discussion403 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. Also used in case where OAuth authorization credentials are present, but the user identity is
not authorized to access the protected resource. Discussion404 NOT FOUNDThe server has not found a resource (such as a feed or
entry) that matches the request URI.405 METHOD NOT ALLOWEDThe 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 CONFLICTThe 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 ERRORInternal error. This is the default code that is used for
all unrecognized errors.501 NOT IMPLEMENTEDThe request was valid but has not been implemented by the
provider. A container SHOULD return 501 NOT IMPLEMENTED when receiving a
request for an OPTIONAL/MAY feature that the container does not
implement.All requests MUST support the following parameters:Request-Parameter-UpdatedSince-Value = When specified the container should only return
items whose updated date & time is equal to or more recent then the
specified value. The value MUST be a valid
(e.g. 2008-01-23T04:56:22Z).JSON is the standard format adopted by OpenSocial.Request-Parameter-Formet-Value = "json" / "xml" / "atom"Specifies the desired return encoding of the request.
Must be one of "json", "xml", or "atom".All requests that return a Collection of objects MUST support the following parameters:Request-Parameter-Count-Value = numberThe page size for a paged collection. If no parameter
is specified the container can choose how many items in the collection
should be returned. However, the container SHOULD support a large default
count value so that all items can be returned by default.Request-Parameter-FilterBy-Value = stringFor a collection, return entries filtered by the
given field name.Request-Parameter-FilterOp-Value = "contains" / "equals" / "startsWith" / "present"The operation to use when filtering a collection by
a field specified in 'filterBy', defaults to "contains". Valid values:
Return elements where filterValue appears
somewhere in the element's filterBy field value.Return elements where filterValue exactly matches
the element's filterBy field value.Return elements where filterValue exactly
matches the first N characters of the element's filterBy field value,
where N is the length of the filterValue string.Return elements where the element's filterBy field
value is not empty or null.Request-Parameter-FilterValue-Value = stringThe value to use when filtering a collection. For example:
{ ... "filterBy" : "name", "filterOp" : "startsWith", "filterValue" : "John" ... }
returns all items whose name field starts with John. Johnny and John
Doe would both be included.)Request-Parameter-SortOrder-Value = "ascending" / "descending"Can either be 'ascending' or 'descending',
defaults to ascending. Used to sort objects in a collection.Request-Parameter-StartIndex-Value = numberIndex into a paged collection.This will return nothing if the other ID is not a friend, the
current user if the two are friends. filterValue may take a specific person
identifier of @owner or @viewer.This will return the set of mutual friends between the current
user and someUserId. filterValue may take a specific person identifier of
@owner or @viewer.Note: The container is not required to support all values for filtering,
sorting and getting the last set of updated items from a collection. If the
container does not respect the filer, sort or updatedSince param the
response should contain "filtered : false", "sorted : false", or
"updatedSince : false".A container declares what collection and features it supports, and
provides templates for discovering them, via a simple discovery document. A
client starts the discovery process at the container's identifier URI (e.g.,
example.org). The full flow is available at http://xrds-simple.net/core/1.0/;
in a nutshell:
Client GETs {container-url} with Accept: application/xrds+xmlContainer responds with either an X-XRDS-Location: header pointing to
the discovery document, or the document itself.If the client received an X-XRDS-Location: header, follow it to get the
discovery document.Once the client has the XRDS document, they have the complete set of
services supported by that service. All OpenSocial service types declare the
base URI in the XRDS URI element. Each service type declares the root URI
for the service. Service specific parameters are passed to each endpoint
using a fixed URI format. This format is defined by each service. The
discovery document is an XML file in the same format used for OpenID and
OAuth discovery, defined at http://xrds-simple.net/core/1.0/:
Each Service advertises a service provided by the container. Each
container MUST support the service Types documented below and MAY support
others by advertising them in the discovery document. Each service comprises
a set of resources defined by the given URI Template (or URI, if there is
only a single resource). Clients follow the URIs and instantiate the
templates to find and operate on specific resources. (URI Template syntax is
documented at
http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt.)The set of substitution variables is fixed for each service Type. The
core set of service Types and their substitution variables is documented
below. Extensions to OpenSocial SHOULD document their substitution
variables; note that a reasonable place to put human readable documentation
is at the namespace URI.The cache service is used to manage the resources cached by the container for a given application.An application can execute an invalidation request as a POST to the Cache service. Requests include a list of URLs associated with resources that should have their cache invalidated. Invalidation keys can include the URL of the gadget spec, associated message bundle files, static resources (e.g. images, CSS), or remote content fetched via osapi.http.Containers MUST support the invalidation endpoint even if they do not
perform any caching and MUST provide an entry for it in their XRDS. To
invalidate content a developer's backend notifies the container of the
content it wishes to invalidate by making a 2-legged OAuth call to the
Cache service with one or many keys to be invalidated. The consumer key
in the 2-legged OAuth call is used by the container to identify the calling
application.Containers MAY reject invalidation requests for policy reasons. Containers MAY continue to serve content that has already been invalidated until the container is able to successfully fetch a replacement from it original source.Response codes have the following meanings:200 - Success, all invalidations processed successfully.403 - Forbidden because authentication failed.409 - The request was partially processed, the set of invalidation keys that were not honored MUST be included in the response body in the format the request was made.XRDS Type: http://ns.opensocial.org/2008/opensocial/cache/invalidateRequests and responses for the Cache service's Invalidate method use the following values:REST-HTTP-Method = "POST"
REST-Request-URI = "/cache/invalidate"
REST-Request-Parameters = null
REST-Request-Payload = Invalidation-Key-ListRPC-Method = "cache.invalidate"
RPC-Request-Parameters = Invalidation-Key-ListReturn-Object = [ Invalidation-Key-List ]
Here is an example that invalidates the cache for the gadget spec and message bundle of an application using REST:
POST /api/rest/cache/invalidate HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
{
"invalidationKeys" : [
"http://www.myapp.com/gadgetspec.xml",
"http://www.myapp.com/messagebundle.xml"
]
}
Here is an example illustrates how information for users and a static
resources can be invalidated using RPC. The example shows how
to specify a user with a global ID (i.e. an ID which includes the domain of the
container) or a relative ID. The static resource in this example is the
gadget spec itself.
POST /api/rpc
Host: api.example.org
Content-Type: application/json
{
"method" : "cache.invalidate",
"params" : {
"invalidationKeys" : [
"example.org:12345",
"example.org:4567",
"3456778",
"http://www.myapp.com/gadgetpec.xml"
]
}
}
The System service is used to introspect the API server for the set of
available services and operations and for metadata about those
services. The System service only supports the RPC protocol.Containers MUST implement this operation which takes no parameters and
returns an array of all methods supported by the endpoint including the
system methods.Requests and responses to the System service's List Methods method use the following values:RPC-Method = "system.listMethods"
RPC-Request-Parameters = null
Return-Object = [ #String ]
Here's an example using RPC:
POST /api/rpc
Host: api.example.org
Content-Type: application/json
{
"method" : "system.listMethods",
"params" : {}
}
A container which only supports read access to people
and read and create access for activities would include the following Return-Object in the response:
[
"people.get",
"activities.get",
"activities.create",
"system.listMethods",
"system.methodSignatures",
"system.methodHelp"
]Containers MUST implement this operation that returns a method
signature describing the types of the parameters, their default values and
the type of the return value for a given operation. Note that this scheme
does not match that used for XML-RPC definition of method signatures which
only specifies a mapping for positional parameters. Type definitions used
here match the scheme used in the OpenSocial Javascript API.RPC-Method = "system.methodSignatures"
RPC-Request-Parameters = { <"> "methodName" <"> ":" String "}"
Return-Object = Method-Signatures
Method-Signatures = "{"
<"> "return" <"> ":" ( String-Value / String-List ) ","
#Parameter-Spec
"}"
Parameter-Spec = Param-Name ":" "{"
<"> "type" <"> ":" ( String-Value / String-List ) ","
[ <"> "default" <"> ":" ( "null" / String-Value / String-List ) "," ]
[ <"> "required" <"> ":" <"> false <"> ]
"}"
Param-Name = String-Value
String-Value = <"> String <">
String-List = "[" #String-Value "]"
The "return" field indicates the type of the result. If the
service can return more than one type then the value is an array of the
possible return types. Each named field in the response maps to a
parameter of the operation and contains information about the types and
values accepted for that parameter. The existence of "default" in the
parameter detail indicates the parameter has a default value. The value of
a default may be null which means that its not introspectable and usually
means that it is some complex derivation. Parameters are assumed to be
required unless otherwise indicated by the existence of the "required"
field with a value of false.Here is an example of a request for the method signature of people.get.
POST /api/rpc
Host: api.example.org
Content-Type: application/json
{
"method" : "system.methodSignatures",
"params" : { "methodName" : "people.get" }
}
Here is the response to a request for the method signature of people.get.
{
"return" : ["opensocial.Person", "Array.<opensocial.Person>"],
"auth" : {
"default" : null,
"type" : "AuthToken"
},
"userId" : {
"default" : "@me",
"type" : ["String", "Array.<String>"]
},
"groupId" : {
"default" : "@self",
"type" : "String"
},
"fields" : {
"default" : ["id","name","thumbnailUrl","profileUrl"],
"type" : "Array.<String>"
},
"count" : {
"type" : "int",
"required" : false
},
"startIndex" : {
"type" : "int",
"required" : false
}
}
Containers MAY implement this operation that returns a textual
description of the operation identified by the methodName parameter. A
container can choose to return either plaintext or HTML as the
response.RPC-Method = "system.methodHelp"
RPC-Request-Parameters = { <"> "methodName" <"> ":" <"> String <"> "}"
Return-Object = String
Here's a request to get the help content for the people.get method.
POST /api/rpc
Host: api.example.org
Content-Type: application/json
{
"method" : "system.methodSignatures",
"params" : { "methodName" : "people.get" }
}
The response might be something like:
Used to fetch profile information about people.
OpenSocial containers MAY support concurrency control to
prevent multiple clients from overwriting each other's data. The mechanism supported by OpenSocial uses the
standard HTTP/AtomPub optimistic concurrency mechanism based on ETags (see
section 9.5 of
for details; the same mechanism applies regardless
of the data format used for the body of the PUT).Concurrency control is available on a resource-by-resource basis. When
an updateable resource supports concurrency control, the container SHOULD
supply an ETag encoding the resource's current state when supplying a
representation to clients. If a resource does not support optimistic
concurrency, it MUST respond to an update request containing an If-Match:
header with a 403 Not Implemented error.A server which chooses not to support optimistic concurrency SHOULD omit
ETags on its responses for updateable resources. A client SHOULD assume
that optimistic concurrency is not available if no ETag is present.When a client is given an ETag, it MAY supply that ETag in an If-Match:
header on subsequent updates. The semantics are that the client can supply
the new representation and the previous ETag; the server inspects the
current state of the resource and applies the update if the client supplied
ETag matches (meaning no intervening updates have happened), otherwise
responds with a 409 Conflict error and the new ETag. Clients may then take
appropriate actions to resolve the conflict, or fail the operation,
depending on their needs. Clients are also free to use PUT to simply
overwrite a resource with a new state at any time, ignoring possible
overwriting problems.If partial updates are supported (see below), a server MUST accept an
ETag given for either a base resource or a projection of that resource upon
a subsequent PUT for that resource. That is, it is legal to supply an ETag
you received when GETting the full representation of a resource even if you
are only PUTting back a single field. If you intend to simply overwrite
that single field, then you skip sending any ETag.Partial updates avoid the need to send full representations of data on
updates, especially for People and App Data. The primary use case is when a
client has retrieved a full representation and subsequently wishes to send
a small update to a server. In the most general case, the client may have a
series of small updates (e.g., changing tags on a large number of contacts)
scattered across many resources. To accomplish these partial updates we
will take advantage of the "fields" parameter.When the "fields" parameter is specified on a url, only those fields
will be looked at when updating an object. If a field is in the parameter
list but not part of the post, that would be considered a removal of that
field. If the field is in the post but not in the parameter list a 400 bad
request error will be returned. If a field is in both places then it will
be updated normally.This example demonstrates the use of etags to detect an incompatible
update to the profile of the user identified in the auth token. The request
is attempting to update the 'books' field and passes the etag the client
received when it retrieved the person object prior to update. The etag is
added to the update request shown below but an intervening update from
another client has made the change incompatible and so the update is
rejected.Notes:
The error code 409 is the HTTP Conflict status code.The error object "data" field contains a limited representation of the
latest version of the person object including an up-to-date etag value.
Containers MAY omit this data from conflict error responses.Fix Gadget XSDOAuth 2.0 SupportContent Upload spec consistency check/cleanupAllow a 403 FORBIDDEN response for insufficient privilegesAlign the REST core and social API server spec to follow the core data spec for Collection type wrapped with "list" propertyResponse codes using REST protocolASCII format for Network InterchangeKey words for use in RFCs to Indicate Requirement LevelsHarvard UniversityAugmented BNF for Syntax Specifications: ABNFReserved Top Level DNS NamesIBMHypertext Transfer Protocol -- HTTP/1.1Uniform Resource Identifier (URI): Generic SyntaxThe Atom Syndication FormatThe application/json Media Type for JavaScript Object Notation (JSON)
The Atom Publishing ProtocolGoogleNewBay SoftwareRison - Compact Data in URIsXML Schema Part 2: Datatypes Second EditionKaiser Permanente, for Health Level SevenMicrosoftJSON-RPC 2.0 Specification proposalXML-RPC IntrospectionOAuth Core 1.0GoogleTwitterPownceFlickrma.gnoliaGoogleTwittersix apartYeddama.gnoliaJaikuOAuth Consumer Request 1.0 Draft 1The OAuth 2.0 Authorization ProtocolYahoo !FacebookMicrosoftOpenSocial Core Data SpecificationOpenSocial Social Data SpecificationDiscussionDiscussion