{"@attributes":{"ipr":"full3978","docName":"opensocial-core-api-server-specification-2-5-1"},"front":{"title":"OpenSocial Core API Server Specification 2.5.1","author":{"@attributes":{"fullname":"OpenSocial and Gadgets Specification Group"},"address":{"email":"opensocial-and-gadgets-spec@googlegroups.com"}},"date":{"@attributes":{"month":"August","year":"2013"}},"abstract":{"t":"This document describes a method for making information\n   and services programatically available on the internet."}},"middle":{"section":[{"@attributes":{"title":"Notation and Conventions"},"section":[{"@attributes":{"title":"Requirements"},"t":["The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\",\n    \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this\n    document are to be interpreted as described in \n    .","An implementation is not compliant if it fails to satisfy one or more of\n    the MUST or REQUIRED level requirements for the protocols it\n    implements."]},{"@attributes":{"title":"Conventions"},"t":"Domain name examples use \n    ."},{"@attributes":{"title":"Augmented BNF"},"t":"The grammatical rules in this document are to be interpreted as\n    described in .  The following constructs are introduced in this document to augment \n    RFC2234:","list":{"@attributes":{"style":"hanging"},"t":[{"@attributes":{"hangText":"{rule1 rule2}"},"t":["Elements enclosed in braces (squiggly brackets) are treated as a\n      single, UNORDERED element. Its contents may occur in any order. Hence: \n      \n      would match (elem foo bar) and (foo elem bar).","NOTE: Specifying alternatives is quite different from specifying set\n      grouping. Alternatives indicate the matching of exactly one (sub-)rule\n      out of the total grouping. The set mechanism indicates the matching of a\n      string which contains all of the elements within the group; however the\n      elements may occur in any order."]},"A construct \"#\" is defined, similar to \"*\", for\n     defining lists of elements. The full form is \"<n>#<m>element\"\n     indicating at least <n> and at most <m> elements, each\n     separated by one or more commas (\",\") and OPTIONAL linear white space\n     (LWS). This makes the usual form of lists very easy; a rule such as \n     \n     can be shown as \n     \n     Wherever this construct is used, null elements are allowed, but do\n     not contribute to the count of elements present. That is, \"(element), ,\n     (element) \" is permitted, but counts as only two elements. Therefore, \n     where at least one element is required, at least one non-null element MUST \n     be present.  Default values are 0 and infinity so that \"#element\" allows \n     any number, including zero; \"1#element\" requires at least one; and \n     \"1#2element\" allows one or two.","A construct \"&\" is defined, similar to \"#\",\n     which uses an ampersand (&) instead of commas, and MUST NOT include\n     linear white space between elements.","The grammar described by this specification is\n     word-based. Except where noted otherwise, linear white space (LWS) can be\n     included between any two adjacent words (token or quoted-string), and\n     between adjacent words and separators, without changing the interpretation\n     of a field. At least one delimiter (LWS and\/or separators) MUST exist\n     between any two tokens, since they would otherwise be interpreted as a\n     single token."]}},{"@attributes":{"title":"Basic Rules"},"t":"The following rules are used throughout this specification to describe\n    basic parsing constructs. The US-ASCII coded character set is defined by \n     ","artwork":{"@attributes":{"type":"abnf"}}}]},{"@attributes":{"title":"Protocols"},"t":"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 . Common data types for social applications are documented in the .","section":[{"@attributes":{"title":"REST"},"t":["The REST protocol defines a language and platform neutral protocol for clients to\n   interact with OpenSocial container servers outside of gadgets on a web page.\n   As a protocol, it is intended to be reasonably easy to implement in any\n   language and on any platform. It should also be usable across a range of\n   clients, from gadgets operating within a web page to servers communicating\n   to synchronize data about a user.","API Servers MUST support the REST protocol.","The protocol operates primarily in terms of resources and operations on\n   them. It is defined on top of the HTTP protocol, and uses the standard HTTP\n   methods (GET, POST, PUT, DELETE, etc.) to retrieve and change server\n   state.","No single data representation is ideal for every client. This protocol\n   defines representations for each resource in three widely supported formats,\n   , XML, and \n    \/\n   , using a set of generic mapping rules.\n   The mapping rules allow a server to write to a single interface rather than\n   implementing the protocol three times.","OpenSocial container servers are free to define additional\n   representations but MUST support at least the JSON and Atom formats for all\n   resources and XML for the people calls. XML MAY be supported for the rest of\n   the resources.","Most operations consist of retrieving (GET), updating (PUT), creating (POST or\n   PUT), or destroying (DELETE) these resources. It also specifies an optional\n   partial update feature which avoids sending large resources over the wire to\n   update just one field."],"section":[{"@attributes":{"title":"REST Request","anchor":"REST-Request"},"t":["A REST request uses the following format:","For example, here is a REST request to retrieve information about a\n     user:"],"artwork":[{"@attributes":{"type":"abnf"}},"\nGET \/api\/people\/@me\/@self?fields=name HTTP\/1.1\nHost: api.example.org\nAuthorization: hh5s93j4hdidpola\nContent-Type: application\/json\n"],"section":[{"@attributes":{"title":"REST-HTTP-Method","anchor":"REST-HTTP-Method"},"t":["Each REST resource defined in this document may specify the exact\n     semantics of each method, but generally, \"GET\" is associated with\n     retrieving a resource, \"POST\" is associated with creating a resource,\n     \"PUT\" is associated with updating a resource, and \"DELETE\" is associated\n     with deleting a resource.","The following HTTP methods may be used for REST requests:","POST is special; it\n   operates on collections and creates new activities, persons, or app data\n   within those collections, and returns the base URI for the created resource\n   in the Location: header, per AtomPub semantics.","Restricted clients, or\n   clients behind restricted clients, which cannot use PUT or DELETE SHOULD\n   translate PUT and DELETE to POST operations with an additional\n   X-HTTP-Method-Override: header: ","Servers SHOULD respond to POST+X-HTTP-Method-Override as if the\n   content of the header were the actual operation sent.","Note that OpenSocial\n   does not support cross-domain JSONP (GET with callback), but servers MAY\n   offer this as an extension. It is RECOMMENDED that such servers implement\n   appropriate security and authorization controls."],"artwork":{"@attributes":{"type":"abnf"}},"figure":{"artwork":"\nPOST \/... HTTP\/1.1\n...\nX-HTTP-Method-Override: PUT\n"}},{"@attributes":{"title":"REST-Request-URI","anchor":"REST-Request-URI"},"t":"The request URI is composed from the base path, a URI fragment, and optional query parameters.","artwork":{"@attributes":{"type":"abnf"}},"section":[{"@attributes":{"title":"REST-Base-Path","anchor":"REST-Base-Path"},"t":"An OpenSocial REST server may choose to expose their REST endpoints in\n     a \"namespaced\" way through use of a path. For example, the REST resource\n     of \"http:\/\/www.example.com\/apis\/people\" would have a REST base path of\n     \"\/apis\", while \"http:\/\/www.example.com\/apis\/opensocial-1.0\/people\" would\n     correspond with the REST base path of \"\/apis\/opensocial-1.0\".","artwork":{"@attributes":{"type":"abnf"}}},{"@attributes":{"title":"REST-URI-Fragment","anchor":"REST-URI-Fragment"},"t":["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.","Each service type defines an associated partial URI format. The base URI\n   for each service is found in the URI element associated with the service in\n   the discovery document. Each service type accepts parameters via the URL\n   path. Definitions are of the form:","Parameters must be filled in using left to right ordering. If a\n   positional pattern is missing, no parameters to the right of that parameter\n   may be filled in. For example, if the preceding pattern was used and only\n   the value of the a parameter was known and set to @me, the complete URL\n   would be expressed as: "],"artwork":{"@attributes":{"type":"abnf"}},"figure":[{"artwork":"\n{a}\/{b}\/{c}\n"},{"artwork":"\n[Discovery URI]\/@me\n"}]},{"@attributes":{"title":"REST-Query-Parameters","anchor":"REST-Query-Parameters"},"t":["Additional parameters for a REST request MAY be passed via the\n     querystring portion of the request URI.","This specification defines a function ENCODE-REST-PARAMETER, which\n     is an alias for encoding a key\/value pair.  The PCT-ENCODE function \n     is described in section 2.1 of .","The FLATTEN function is also defined in this spec, and behaves in\n     the following manner:","The behavior of FLATTEN for input not explicitly covered here is \n     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:"],"artwork":[{"@attributes":{"type":"abnf"}},"\nENCODE-REST-PARAMETER(k,v) = PCT-ENCODE(k) \"=\" PCT-ENCODE(FLATTEN(v))\n","        \nhttp:\/\/www.example.com\/opensocial\/rest\/people\/@me\/@self?fields=name,gender&format=json\n"],"list":{"@attributes":{"style":"numbers"},"t":["If the argument supplied is an array of strings or numbers, the \n      string representation of each array element is returned, with each element\n      separated by a COMMA.","If the argument supplied is a string or a number, the string \n      representation of the argument is returned."]}}]},{"@attributes":{"title":"REST-Request-Payload","anchor":"REST-Request-Payload"},"t":"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."}]},{"@attributes":{"title":"REST Response","anchor":"REST-Response"},"t":"A REST response uses the following format:","artwork":"\nHTTP\/1.x  \n[ \"Content-Type: \"  ]\n[  ]\n","section":{"@attributes":{"title":"REST-Response-Payload","anchor":"REST-Response-Payload"},"t":"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:","artwork":{"@attributes":{"type":"abnf"}},"xref":"Discussion"}}]},{"@attributes":{"title":"RPC"},"t":["The RPC protocol supports\n   the same data and operations as the RESTful API in a form that is more\n   natural for the JSON data format. Any batch of RPCs should be\n   programatically convertible to a sequence or batch of RESTful calls and\n   maintain the same semantics, any exception to this will be called out\n   explicitly.","API Servers MAY support the RPC protocol.","The RPC protocol shares the following with the RESTful protocol:","The RPC protocol differs from the RESTful protocol in the following ways:"],"list":[{"@attributes":{"style":"symbols"},"t":["The JSON\/XML format of the OpenSocial data types such as Person, Activity,\n    Group, AppData are identical.","HTTP status codes are used to represent common error cases where\n    applicable.",{"xref":{"@attributes":{"target":"OAuth-Core-1.0"}}},"Concurrency control is optional."]},{"@attributes":{"style":"symbols"},"t":["Conforms to the  specification","All structural elements in the protocol are represented using the JSON\n    or XML notation.","Batch support is required.","HTTP is used primarily as a transport and not to indicate the semantics\n    of the request.","Automated discovery happens in two steps. XRDS can be used to discover\n    the RPC endpoint. The service can then be introspected by executing a request to the  method to discover the list of available services and\n    operations using conventions defined by . In general it is expected\n    that a large percentage of consumers will bypass automated discovery and\n    rely on simply hardcoding references to the endpoints of various popular\n    containers."]}],"section":[{"@attributes":{"title":"URL Addressing","anchor":"urlAddressing"},"t":["Containers MUST give access to the RPC services using a URL addressing\n   scheme to invoke a single RPC via HTTP GET. This encoding can also be used\n   to support RPC execution via form posts including file-uploads as parameters\n   to RPCs. It is recommended that only services that are idempotent are\n   exported in this manner. Containers MUST use the following canonical\n   transformation between the RPC structure and its URL encoding:","The following provides some examples of mapping JSON objects to URL Parameters:","For example, given the following :","The corresponding URL is:","In situations where containers support the \n    scheme to perform an RPC\n   the container MAY return arbitrary content types in the response other than\n   application\/json. The system.methodHelp operation relies on this to provide\n   browseable documentation."],"list":{"@attributes":{"style":"symbols"},"t":["The RPC method is defined by the 'method' query parameter","The RPC id is defined by the 'id' query parameter","All other query parameters are assumed to belong to the RPC params\n    element and are encoded from JSON using <field path dot\n    notation>=<scalar value> | <comma separated array of\n    scalars>. When a field represents an array of non-scalars then elements\n    of the array are identified by enclosing the index in parenthesis. Strings\n    which match [0-9]+ MUST be single-quoted, Strings which match [A-Za-z_]+\n    MUST be unquoted, all other strings retain their original quoting."]},"texttable":{"@attributes":{"align":"left"},"ttcol":["JSON Object","URL Parameter"],"c":["{ \"field\" : \"value\" }","field=value","{ \"field\" : [1,2,3,4,5]}","field=1,2,3,4,5","{ \"field\" : \"12\" }","field='12'","{ \"field\" :\n[identifier,anotheridentifier]}","field=identifier,anotheridentifier","{ \"field\" : [\"value\",\"another value\"]}","field=value,\"another\nvalue\"","{ \"field\" : ['value','another value']}","field=value,'another\nvalue'","{ \"field\" : { \"nested\" : \"value\" }}","field.nested=value","{ \"field\" : [{ \"nested1\" : \"value1\" }, { \"nested2\" : \"value2\"\n}]}","field(0).nested1=value1&field(1).nested2=value2"]},"artwork":["\n{ \"method\" : \"people.get\", \"id\" : \"myfriends\", \"params\": {\"userId\" : \"@me\", \"groupId\" : \"@friends\" } } \n","\nhttp:\/\/api.example.org\/rpc?method=people.get&id=myfriends&params.userId=@me&params.groupId=@friends\n"]},{"@attributes":{"title":"RPC Request","anchor":"RPC-Request"},"t":["An RPC request uses the following format:","For example, here is a RPC request to retrieve information about a\n     user:"],"artwork":["\nRPC-Request = \"POST \/\"  \" HTTP\/1.1\"\n              \"HOST\" <any valid HTTP host>\n              \"Authorization: \"  \n              \"Content-Type: \"  \n              \n","\nPOST \/rpc HTTP\/1.1\nHost: api.example.org\nAuthorization: hh5s93j4hdidpola\nContent-Type: application\/json\n{\n  \"method\" : \"people.get\",\n  \"id\" : \"myself\"\n  \"params\" : {\n    \"userId\" : \"@me\",\n    \"groupId\" : \"@self\"\n  }\n}\n"],"section":[{"@attributes":{"title":"RPC Base URL","anchor":"RPC-Base-URL"},"t":"The RPC Base URL is defined in the XRDS file."},{"@attributes":{"title":"RPC Request Payload","anchor":"RPC-Request-Payload"},"t":["RPC requests MAY batch multiple procedure calls into a single HTTP\n      request. Therefore, the payload of an RPC request can container a JSON\n      array of procedure calls, or a single procedure call:","Note that the \"json-rpc\" property defined in  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\n      the payload:","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 ."],"artwork":[{"@attributes":{"type":"abnf"}},"\nPOST \/rpc HTTP\/1.1\nHost: api.example.org\nAuthorization: hh5s93j4hdidpola\nContent-Type: application\/json\n[\n  {\n    \"method\" : \"people.get\",\n    \"id\" : \"myself\",\n    \"params\" : {\n      \"userId\" : \"@me\",\n      \"groupId\" : \"@self\"\n    }\n  },\n  {\n    \"method\" : \"people.get\",\n    \"id\" : \"myfriends\",\n    \"params\" : {\n      \"userId\" : \"@me\",\n      \"groupId\" : \"@friends\"\n    }\n  }\n]\n","\nPOST \/rpc HTTP\/1.1\nHost: api.example.org\nAuthorization: <1st Auth token>\nContent-Type: application\/json\n[\n  {\n    \"method\" : \"people.get\",\n    \"id\" : \"profileOfAlice\"\n    \"params: {\n      \"userId\" : \"09737549474\",\n    }\n  },\n  {\n    \"method\" : \"people.get\",\n    \"id\" : \"profileOfBob\",\n    \"params: {\n      \"userId\" : \"34906734059\",\n      \"auth\" : \"<2nd Auth token>\"\n    }\n  }\n]\n"]},{"@attributes":{"title":"RPC Method","anchor":"RPC-Method"},"t":["The value of the \"method\" field in an OpenSocial RPC request uses a\n    format of \"<service-name>.<operation>\". <service-name> is\n    a string [A-Za-z0-9_]+ that identifies one of the services listed in\n    [Services] and <operation> is a string [A-Za-z0-9_]+ that identifies\n    an operation supported by that service.","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\n    GET, PUT, POST & DELETE.","Available methods can be determined by calling the \n        method."],"artwork":{"@attributes":{"type":"abnf"}}},{"@attributes":{"title":"RPC Request Parameters","anchor":"RPC-Request-Parameters"},"t":["Parameters can be passed to RPC methods in the request payload as a\n       JSON object as described in ","Appropriate values for RPC request parameters can be determined by\n       calling the \n        method.","Here is an example of an RPC request payload with procedure-specific\n       parameters (userId, groupId) and standard OpenSocial parameters:","This specification defines a function ENCODE-RPC-PARAMETER which is\n       an alias for the JSON encoding process.  This function takes a key and\n       value as arguments, where the key must be a string, and the value must\n       have a valid JSON encoding."],"artwork":["\n{\n  \"method\" : \"people.get\",\n  \"id\" : \"myself\"\n  \"params\" : {\n    \"userId\" : \"@me\",\n    \"groupId\" : \"@self\",\n    \"fields\" : \"name, gender\",\n    \"format\" : \"json\"\n  }\n}","ENCODE-RPC-PARAMETER(k,v) = \"{\" <\"> k <\"> \":\" JSON-ENCODE(v) \"}\")"]}]},{"@attributes":{"title":"RPC Response","anchor":"RPC-Response"},"t":"An RPC response uses the following format:","artwork":"\nHTTP\/1.x 207 Multi-Status\n\"Content-Type: \"  \n\n","section":[{"@attributes":{"title":"RPC-Response-Payload","anchor":"RPC-Response-Payload"},"t":["RPC responses MAY contain results from multiple procedure calls, if\n      the corresponding HTTP request contained a \n      .  The batch response elements MUST be returned in the same order\n     as the corresponding batch request elements and the \"id\" property of the corresponding\n     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 \n       object with the appropriate error message and\n      code.","The response payload for a single procedure call MUST contain an 'id'\n      property to correlate the response with a request. On success, the\n      payload MUST contain a 'result' property. On failure, the payload MUST contain an 'error'\n      property.  Each service method defines the object that is included as the Return-Object.","The following examples illustrate how success and failure are\n      represented in responses to batch requests. \n      \n      \n      \n      \n      \n      \n      \n      "],"artwork":{"@attributes":{"type":"abnf"}}},{"@attributes":{"title":"RPC Error","anchor":"RPC-Error"},"t":["An error object MUST contain a 'code' property to indicate the actual\n      error that occurred and MAY contain a 'message' property describing the\n      error. Additional information may be returned in the 'data' property, as\n      defined by the procedure.","A common set of error codes are used to represent failure modes that\n   apply generally to operations and so are reserved for use by this\n   specification.","Here is an example of an unsuccessful RPC response payload:"],"artwork":["\nRPC-Error = \"{\"\n              [ <\"> \"message\" <\"> \":\" <\"> string <\"> \",\" ]\n              [ <\"> \"data\" <\"> \":\" <any JSON object> \",\" ]\n              <\"> \"code\" <\"> \":\" integer \",\"\n            \"}\"\n","\n{\n  \"id\" : \"myself\"\n  \"error\" : {\n    \"code\" : 401\n    \"message\" : \"The authorization token does not provide access to the requested resource.\"\n  }\n}\n"],"texttable":{"@attributes":{"align":"left"},"ttcol":["Code","Meaning"],"c":["-32700 (Parse error)","Invalid JSON. An error occurred on the server while parsing the JSON\n       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..-32000","Reserved 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-1000","Reserved for future use by this specification."]}}]}]}]},{"@attributes":{"title":"Security","anchor":"Security"},"t":"OpenSocial Containers MUST support TLS 2.0 \/ SSL connections for sensitive data \n      since OAuth on its own does not provide encryption or message body integrity checking.\n      Note that TLS 2.0\/SSL is required with many scenarios in the OAuth 2.0 specification.","section":[{"@attributes":{"title":"OAuth 1.0a Support"},"t":["Core Gadget Servers MUST support Open Authorization 1.0a  \n      but SHOULD use appropriate policies to determine which operations are allowed on a per-consumer and \n      per-user basis.","When OAuth 1.0a is used for authorization on a single RPC, the OAuth signature\n        uses the  representation of the\n        request without the authorization parameter, in order to calculate the signature base string."]},{"@attributes":{"title":"OAuth 2.0 Support"},"xref":"Discussion","t":["Core Gadget Servers MUST support the authorization server, resource server and client roles\n      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\n      specification.\n      A Core Gadget Server MUST implement the authorization code and client credential types described in section 4 of the\n      Open Authorization 2.0 specification.  Core Gadget Servers SHOULD implement the implicit grant type.\n      Core Gadget Servers MAY implement the refresh token pattern described \n      in section 1.5 of  the OAuth 2.0 specification."]},{"@attributes":{"title":"Two Party OAuth Optional Parameters"},"t":"For 2 party (client credential) OAuth requests, if a Core Gadget Server has a user identifier\n      and wishes to indicate that the\n      operation is being done on behalf of that particular user, it SHOULD provide\n      the OAuth extension parameter xoauth_requestor_id along with the OAuth\n      parameters as a query fragment.  Often times, the value for the xoauth_reqeustor_id\n      will be set to the e-mail address of the \n      user, on who's behalf the Core Gadget Server is making the call.\n      Core Gadget Servers SHOULD only provide the xoauth_requestor_id if the user has given prior\n      consent to the operation or class of operations being done on their behalf.\n      Core Gadget Servers MUST either honor the parameter or ignore it as if it were not\n      provided."},{"@attributes":{"title":"Client Registration"},"t":["OpenSocial Containers may wish to restrict requests from unknown clients and require gadget registration, \n      in order to mitigate risk. OpenSocial Containers SHOULD document how to register a gadget with the OpenSocial\n      Container in order to obtain a client identifier and client secret.  This is typically done through a web page,\n      although the exact method is left to the specific implementation.","Note that per the security considerations \n      mentioned in the OAuth 2.0 specification, client secrets should not be issued to untrusted clients.","OpenSocial Containers SHOULD document how to store client identifiers and client secrets on the server in order for\n      a gadget running locally to access remote data in another server."],"xref":"Discussion"},{"@attributes":{"title":"Redirection during 3 Party OAuth"},"t":"OpenSocial Containers SHOULD document how the OpenSocial Container handles redirection when authenticating\n      a user and obtaining authorization for a gadget. Note that this is a potential vector for phishing if the \n      user is required to enter their credentials.  Normally, for three-party OAuth exchanges, the OpenSocial \n      Container will provide a web page \n      to collect authentication and scoped authorization information, although the exact method is left to the \n      specific implementation."},{"@attributes":{"title":"Security Considerations"},"t":["OpenSocial Containers SHOULD base their security decisions on the type of client in use; \n      a generally available desktop client, for example, cannot effectively protect a client secret that \n      is installed with each client (implicit grant). The security of communications with a two-party partner \n      service, on the other hand, is dependent on the effectiveness of that service's security procedures\n      (client credential grant).","  The security of communications with a three party service, involving a \n      registered server, a client\/gadget and the OpenSocial Container, should follow the security guidelines \n      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 \n      possible (e.g., allow reading but not writing if a client only performs reads)."],"xref":"Discussion"},{"@attributes":{"title":"Access Token Scopes and Expiration Times"},"t":"OpenSocial Containers SHOULD issue access tokens with short expiration times to limit the scope \n      of security breaches due to stolen access tokens.  The token expiration policy is left to the \n      specific implementation and may vary depending on the client requesting the token.  \n      Expiration times of 1 hour or less, and tokens with limited scope may be used with less \n      trusted clients while expiration times of several hours and tokens with increased scope may be \n      used for more trusted clients.  An OpenSocial Container SHOULD document (at least for administrators)\n      how to configure token scopes and expiration times if these values are configurable."},{"@attributes":{"title":"Gadget Request Context"},"t":"Each API call from a gadget to the Core Gadget Server has a request context that usually includes\n           authentication and authorization information. Typically, the context\n           information includes the requester id (the user initiating the request) and\n           app Id (the application, or whatever is acting as the user's agent). It may\n           include other core container-specific information.  The requesting application\n           and user may be implied through the OAuth tokens, or may be provided explicitly\n           in the xoauth_requestor_id optional parameter.  Request contexts can also\n           include things such as cookies, URI parmaters, client SSL certificates and\n           other information."},{"@attributes":{"title":"Anonymous access to data"},"t":["An OpenSocial Container may accept\n        requests with no authentication or authorization information\n        for public data. A container may provide a public version (e.g., of a\n        profile) if no authorization information is provided.","Note that the data provided for a given RESTful URI MAY vary per\n        requestor or application. The data returned from a resource URI is \"the\n        view of the information available to the current requestor\/application combination\"."]},{"@attributes":{"title":"Data Access Return Codes"},"t":"In the case where no information is available due to lack of authorization,\n        an HTTP 401 Unauthorized response SHOULD be returned to the client. In the\n        case where at least some view of the information is available, it SHOULD be\n        returned using a 200 status, with a standard OAuth WWW-Authenticate: header\n        indicating that additional information may be available when using a\n        different authorization context."}]},{"@attributes":{"title":"Content Upload","anchor":"Content-Upload"},"section":[{"@attributes":{"title":"Two Step Upload","anchor":"twoStepUpload"},"xref":"Discussion","t":["Content Upload is a generic mechanism to allow for a standard way to\n     upload content.  This mechanism MAY be used to upload to an\n     existing Album, MediaItem endpoint, or where appropriate. In most scenarios an uploaded\n     content is associated with creation of an entity. Upload of content\n     routinely causes the creation of the entity. For example, uploading a\n     photo causes the container to create a new media item. The application can\n     then update that MediaItem and set attributes via a second request at some\n     later time. The requests look like: \n     The two step request process is illustrated below.","Step 1: Upload the image in the album. \n     \n     ","Step 2: PUT MediaItem details to MediaItem (id:223344) ","Note: response includes \"caption\" in addition to \"title\".  \n\t Caption is being deprecated in the 1.0 data format and will be removed\n\t entirely in a future version of the spec.\n     \n     The response indicates that the media item was updated."]},{"@attributes":{"title":"Shortcut Upload Method"},"t":"The shortcut upload mechanism is OPTIONAL. This two step process shown\n     above can be merged into one by a single POST request with the content\n     type set to the item being uploaded. The POST URL can optionally pass the\n     attributes. The Accept-type indicates the format of the response expected.\n     \n     \n     "},{"@attributes":{"title":"Multi-part Uploads"},"t":["A container MAY choose to support file uploads from browsers to the RPC\n   endpoint and have the uploaded files be passed as parameters to the RPC.\n   This is achieved by browsers posting a form which contains the files to the\n   endpoint and including a form-parameter called \"request\" which contains the\n   form-encoded RPC request. The form input element names for the uploaded\n   files will be bound to the corresponding parameter names on execution.","A multipart form-data request mechanism (\"Content-Type:\n    multipart\/form-data\") enables upload of content. Such a request has the\n    POST body segmented into several sections (fields) with each field\n    identified by a name. The field name \"request\" is reserved and contains\n    request operation details (same as the contents on the POST body in the\n    vanilla POST operation).","The fields with any other name contain content to be uploaded to the\n    OpenSocial container. To allow batching and multiple file uploads in a\n    single call, multiple fields (identified with unique field names) are\n    allowed. The OpenSocial request can refer to the content being uploaded by\n    setting the URL to \"@field:<fieldname>\". The container may host the\n    uploaded file and replace the URL field with a fully qualified URL for\n    future access.","For a successful upload, the response code of the request will be\n    associated with the response code of the action request on the resource.\n    However, in case of a failure due to a file size exceeding limits, an error\n    code of 413 (\"Request Entity Too Large\") MUST be returned. The requested\n    action associated with the file upload MUST NOT be executed.",{"figure":{"preamble":"Example:","artwork":"\n<usual headers>\nContent-type: multipart\/form-data; boundary=------------abcdef012345xyZ\nContent-length: <contentLength>\n------------abcdef012345xyZ\nContent-Disposition: form-data; name=\"request\"\n[{\n  \"method\":\"activities.create\",\n  \"params\": {\n    \"userId\":[\"@viewer\"],\n    \"groupId\":\"@self\",\n    \"appId\":\"@app\",\n    \"activity\": {\n      \"title\": \"hello world!\",\n      \"mediaItems\": [ {\n        \"mimeType\":\"image\",\n        \"url\":\"@field:image1\"\n      } ]\n    }\n  },\n  \"id\":\"key\"\n}\n------------abcdef012345xyZ\nContent-Disposition: form-data; name=\"image1\"\nGIF89....<image data>\n------------abcdef012345xyZ\n"}}]}]},{"@attributes":{"title":"Common Elements"},"section":[{"@attributes":{"title":"Request-ID","anchor":"Request-ID"},"t":"A string identifying a request."},{"@attributes":{"title":"Auth-Token","anchor":"Auth-Token"},"t":"A string used to authenticate a request."},{"@attributes":{"title":"Content-Type","anchor":"Content-Type"},"t":"A string used to identify the type of content in a request or response."},{"@attributes":{"title":"Return-Object","anchor":"Return-Object"},"t":"The actual content included in the response. Each service method defines the object that is included as the Return-Object."},{"@attributes":{"title":"Invalidation-Key-List","anchor":"Invalidation-Key-List"},"t":["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\n    they can be distinguished from ids. Each request accepts a repeated group\n    of keys."],"artwork":{"@attributes":{"type":"abnf"},"eref":"Object-Id"}},{"@attributes":{"title":"HTTP-Status-Code","anchor":"HTTP-Status-Code"},"texttable":{"ttcol":["Status Code","Description"],"c":["400 BAD REQUEST","OpenSocial application servers MUST return 400 BAD REQUEST\n    under any one or more of the following conditions: \n    ","401 UNAUTHORIZED","\n    \n    OpenSocial container servers MUST return 401 UNAUTHORIZED\n    when receiving an OAuth request for a protected resource and the request is either\n    \n    ","403 FORBIDDEN","\n    The server understood the request but is refusing to\n    fulfill it. Authorization will not help. The current authorization context\n    does not allow the request.  Also used in case where OAuth authorization credentials are present, but the user identity is\n     not authorized to access the protected resource. ","404 NOT FOUND","The server has not found a resource (such as a feed or\n    entry) that matches the request URI.","405 METHOD NOT ALLOWED","The method specified in the Request-Line is not allowed for\n    the resource identified by the Request-URI. The response MUST include an\n    Allow header containing a list of valid methods for the requested\n    resource.","409 CONFLICT","The request could not be completed due to a conflict with the current\n    state of the resource. This code is only allowed in situations where it is\n    expected that the user might be able to resolve the conflict and resubmit\n    the request. The response body SHOULD include enough information for the\n    user to recognize the source of the conflict. Ideally, the response entity\n    would include enough information for the user or user agent to fix the\n    problem; however, that might not be possible and is not required. Conflicts\n    are most likely to occur in response to a PUT request. For example, this\n    code can be used for a limit exceeded error as well as conflicting updates.\n    See the error message for more information.","500 INTERNAL SERVER ERROR","Internal error. This is the default code that is used for\n    all unrecognized errors.","501 NOT IMPLEMENTED","The request was valid but has not been implemented by the\n    provider. A container SHOULD return 501 NOT IMPLEMENTED when receiving a\n    request for an OPTIONAL\/MAY feature that the container does not\n    implement."]}}]},{"@attributes":{"title":"Request Parameters"},"section":[{"@attributes":{"title":"Standard Request Parameters","anchor":"Standard-Request-Parameters"},"t":"All requests MUST support the following parameters:","section":[{"@attributes":{"title":"Updated Since","anchor":"Request-Parameter-UpdatedSince-Value"},"artwork":{"@attributes":{"type":"abnf"},"xref":{"@attributes":{"target":"XSdateTime"}}},"t":"When specified the container should only return\n     items whose updated date & time is equal to or more recent then the\n     specified value. The value MUST be a valid \n      (e.g. 2008-01-23T04:56:22Z)."},{"@attributes":{"title":"Format","anchor":"Request-Parameter-Format-Value"}}]},{"@attributes":{"title":"Collection Request Parameters","anchor":"Collection-Request-Parameters"},"t":"All requests that return a Collection of objects MUST support the following parameters:","section":[{"@attributes":{"title":"Count","anchor":"Request-Parameter-Count-Value"},"artwork":{"@attributes":{"type":"abnf"}},"t":"The page size for a paged collection. If no parameter\n       is specified the container can choose how many items in the collection\n       should be returned. However, the container SHOULD support a large default\n       count value so that all items can be returned by default."},{"@attributes":{"title":"Filter By","anchor":"Request-Parameter-FilterBy-Value"},"artwork":{"@attributes":{"type":"abnf"}},"t":"For a collection, return entries filtered by the\n     given field name."},{"@attributes":{"title":"Filter Operation","anchor":"Request-Parameter-FilterOp-Value"},"artwork":{"@attributes":{"type":"abnf"}},"t":"The operation to use when filtering a collection by\n     a field specified in 'filterBy', defaults to \"contains\". Valid values: \n     "},{"@attributes":{"title":"Filter Value","anchor":"Request-Parameter-FilterValue-Value"},"artwork":[{"@attributes":{"type":"abnf"}},"\n{ ... \"filterBy\" : \"name\", \"filterOp\" : \"startsWith\", \"filterValue\" : \"John\" ... }\n"],"t":["The value to use when filtering a collection. For example: ","returns all items whose name field starts with John. Johnny and John\n      Doe would both be included.)"]},{"@attributes":{"title":"Sort Order","anchor":"Request-Parameter-SortOrder-Value"},"artwork":{"@attributes":{"type":"abnf"}},"t":"Can either be 'ascending' or 'descending',\n     defaults to ascending. Used to sort objects in a collection."},{"@attributes":{"title":"Start Index","anchor":"Request-Parameter-StartIndex-Value"},"artwork":{"@attributes":{"type":"abnf"}},"t":"Index into a paged collection."},{"@attributes":{"title":"Examples"},"figure":[{"preamble":"Behavior of query parameters to determine if two people are\n     friends (important part is the query string):","artwork":"\n\/people\/@me\/@self?filterBy=@friends&filterOp=contains&filterValue=<someUserId>\n"},{"preamble":"To determine the mutual friends between two people (important\n     part is the query string):","artwork":"\n\/people\/@me\/@friends?filterBy=@friends&filterOp=contains&filterValue=<someUserId>\n"}],"t":["This will return nothing if the other ID is not a friend, the\n    current user if the two are friends. filterValue may take a specific person\n    identifier of @owner or @viewer.","This will return the set of mutual friends between the current\n    user and someUserId. filterValue may take a specific person identifier of\n    @owner or @viewer.","Note: The container is not required to support all values for filtering,\n    sorting and getting the last set of updated items from a collection. If the\n    container does not respect the filer, sort or updatedSince param the\n    response should contain \"filtered : false\", \"sorted : false\", or\n    \"updatedSince : false\"."]}]}]},{"@attributes":{"title":"Discovery","anchor":"Discovery"},"t":["A container declares what collection and features it supports, and\n   provides templates for discovering them, via a simple discovery document. A\n   client starts the discovery process at the container's identifier URI (e.g.,\n   example.org). The full flow is available at http:\/\/xrds-simple.net\/core\/1.0\/;\n   in a nutshell: \n   Once the client has the XRDS document, they have the complete set of\n   services supported by that service. All OpenSocial service types declare the\n   base URI in the XRDS URI element. Each service type declares the root URI\n   for the service. Service specific parameters are passed to each endpoint\n   using a fixed URI format. This format is defined by each service. The\n   discovery document is an XML file in the same format used for OpenID and\n   OAuth discovery, defined at http:\/\/xrds-simple.net\/core\/1.0\/: \n   ","Each Service advertises a service provided by the container. Each\n   container MUST support the service Types documented below and MAY support\n   others by advertising them in the discovery document. Each service comprises\n   a set of resources defined by the given URI Template (or URI, if there is\n   only a single resource). Clients follow the URIs and instantiate the\n   templates to find and operate on specific resources. (URI Template syntax is\n   documented at\n   http:\/\/www.ietf.org\/internet-drafts\/draft-gregorio-uritemplate-03.txt.)","The set of substitution variables is fixed for each service Type. The\n   core set of service Types and their substitution variables is documented\n   below. Extensions to OpenSocial SHOULD document their substitution\n   variables; note that a reasonable place to put human readable documentation\n   is at the namespace URI."]},{"@attributes":{"title":"Services","anchor":"services"},"section":[{"@attributes":{"title":"Cache","anchor":"Cache-Service"},"t":"The cache service is used to manage the resources cached by the container for a given application.","section":{"@attributes":{"title":"Invalidate","anchor":"Cache-Service-Invalidate"},"t":["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 .","Containers MUST support the invalidation endpoint even if they do not\n    perform any caching and MUST provide an entry for it in their XRDS. To\n    invalidate content a developer's backend notifies the container of the\n    content it wishes to invalidate by making a 2-legged OAuth call to the\n    Cache service with one or many keys to be invalidated. The consumer key\n    in the 2-legged OAuth call is used by the container to identify the calling\n    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:","XRDS Type: http:\/\/ns.opensocial.org\/2008\/opensocial\/cache\/invalidate","Requests and responses for the Cache service's Invalidate method use the following values:","Here is an example that invalidates the cache for the gadget spec and message bundle of an application using REST:","Here is an example illustrates how information for users and a static\n    resources can be invalidated using RPC. The example shows how\n    to specify a user with a global ID (i.e. an ID which includes the domain of the\n    container) or a relative ID. The static resource in this example is the\n    gadget spec itself."],"list":{"@attributes":{"style":"symbols"},"t":["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."]},"artwork":[{"@attributes":{"type":"abnf"}},"\nPOST \/api\/rest\/cache\/invalidate HTTP\/1.1\nHost: api.example.org\nAuthorization: hh5s93j4hdidpola\nContent-Type: application\/json\n{\n  \"invalidationKeys\" : [ \n      \"http:\/\/www.myapp.com\/gadgetspec.xml\", \n      \"http:\/\/www.myapp.com\/messagebundle.xml\"\n  ]\n}\n","\nPOST \/api\/rpc\nHost: api.example.org\nContent-Type: application\/json\n{\n   \"method\" : \"cache.invalidate\",\n   \"params\" : {\n       \"invalidationKeys\" : [ \n           \"example.org:12345\", \n           \"example.org:4567\", \n           \"3456778\", \n           \"http:\/\/www.myapp.com\/gadgetpec.xml\"\n       ]\n   }\n}\n"]}},{"@attributes":{"title":"System","anchor":"System-Service"},"t":"The System service is used to introspect the API server for the set of\n    available services and operations and for metadata about those\n    services.  The System service only supports the RPC protocol.","section":[{"@attributes":{"title":"ListMethods","anchor":"System-Service-ListMethods"},"t":["Containers MUST implement this operation which takes no parameters and\n     returns an array of all methods supported by the endpoint including the\n     system methods.","Requests and responses to the System service's List Methods method use the following values:","Here's an example using RPC:","A container which only supports read access to people\n     and read and create access for activities would include the following Return-Object in the response:"],"artwork":[{"@attributes":{"type":"abnf"}},"\nPOST \/api\/rpc\nHost: api.example.org\nContent-Type: application\/json\n{\n   \"method\" : \"system.listMethods\",\n   \"params\" : {}\n}\n","\n[\n  \"people.get\", \n  \"activities.get\", \n  \"activities.create\",  \n  \"system.listMethods\",\n  \"system.methodSignatures\", \n  \"system.methodHelp\"\n]"]},{"@attributes":{"title":"MethodSignatures","anchor":"System-Service-MethodSignatures"},"t":["Containers MUST implement this operation that returns a method\n     signature describing the types of the parameters, their default values and\n     the type of the return value for a given operation. Note that this scheme\n     does not match that used for XML-RPC definition of method signatures which\n     only specifies a mapping for positional parameters. Type definitions used\n     here match the scheme used in the OpenSocial Javascript API.","The \"return\" field indicates the type of the result. If the\n     service can return more than one type then the value is an array of the\n     possible return types. Each named field in the response maps to a\n     parameter of the operation and contains information about the types and\n     values accepted for that parameter. The existence of \"default\" in the\n     parameter detail indicates the parameter has a default value. The value of\n     a default may be null which means that its not introspectable and usually\n     means that it is some complex derivation. Parameters are assumed to be\n     required unless otherwise indicated by the existence of the \"required\"\n     field with a value of false.","Here is an example of a request for the method signature of .","Here is the response to a request for the method signature of ."],"artwork":[{"@attributes":{"type":"abnf"}},"\nPOST \/api\/rpc\nHost: api.example.org\nContent-Type: application\/json\n{\n   \"method\" : \"system.methodSignatures\",\n   \"params\" : { \"methodName\" : \"people.get\" }\n}\n","\n{\n  \"return\" : [\"opensocial.Person\", \"Array.<opensocial.Person>\"],\n  \"auth\" : {\n     \"default\" : null,\n     \"type\" : \"AuthToken\"\n   },\n   \"userId\" : {\n     \"default\" : \"@me\",\n     \"type\" : [\"String\", \"Array.<String>\"]\n   },\n   \"groupId\" : {\n     \"default\" : \"@self\",\n     \"type\" : \"String\"\n   },\n   \"fields\" : {\n     \"default\" : [\"id\",\"name\",\"thumbnailUrl\",\"profileUrl\"],\n     \"type\" : \"Array.<String>\"\n   },\n   \"count\" : {\n     \"type\" : \"int\",\n     \"required\" : false\n   },\n   \"startIndex\" : {\n     \"type\" : \"int\",\n     \"required\" : false\n   }\n}\n"]},{"@attributes":{"title":"MethodHelp","anchor":"System-Service-MethodHelp"},"t":["Containers MAY implement this operation that returns a textual\n     description of the operation identified by the methodName parameter. A\n     container can choose to return either plaintext or HTML as the\n     response.","Here's a request to get the help content for the people.get method.","The response might be something like:"],"artwork":[{"@attributes":{"type":"abnf"}},"\nPOST \/api\/rpc\nHost: api.example.org\nContent-Type: application\/json\n{\n   \"method\" : \"system.methodSignatures\",\n   \"params\" : { \"methodName\" : \"people.get\" }\n}\n","\nUsed to fetch profile information about people.\n"]}]}]},{"@attributes":{"title":"Concurrency Control"},"t":"OpenSocial containers MAY support concurrency control to \n   prevent multiple clients from overwriting each other's data. The mechanism supported by OpenSocial uses the\n   standard HTTP\/AtomPub optimistic concurrency mechanism based on ETags (see\n   section 9.5 of \n    for details; the same mechanism applies regardless\n   of the data format used for the body of the PUT).","section":[{"@attributes":{"title":"Discovery"},"t":["Concurrency control is available on a resource-by-resource basis. When\n    an updateable resource supports concurrency control, the container SHOULD\n    supply an ETag encoding the resource's current state when supplying a\n    representation to clients. If a resource does not support optimistic\n    concurrency, it MUST respond to an update request containing an If-Match:\n    header with a 403 Not Implemented error.","A server which chooses not to support optimistic concurrency SHOULD omit\n    ETags on its responses for updateable resources. A client SHOULD assume\n    that optimistic concurrency is not available if no ETag is present."]},{"@attributes":{"title":"Semantics"},"t":["When a client is given an ETag, it MAY supply that ETag in an If-Match:\n    header on subsequent updates. The semantics are that the client can supply\n    the new representation and the previous ETag; the server inspects the\n    current state of the resource and applies the update if the client supplied\n    ETag matches (meaning no intervening updates have happened), otherwise\n    responds with a 409 Conflict error and the new ETag. Clients may then take\n    appropriate actions to resolve the conflict, or fail the operation,\n    depending on their needs. Clients are also free to use PUT to simply\n    overwrite a resource with a new state at any time, ignoring possible\n    overwriting problems.","If partial updates are supported (see below), a server MUST accept an\n    ETag given for either a base resource or a projection of that resource upon\n    a subsequent PUT for that resource. That is, it is legal to supply an ETag\n    you received when GETting the full representation of a resource even if you\n    are only PUTting back a single field. If you intend to simply overwrite\n    that single field, then you skip sending any ETag."]},{"@attributes":{"title":"Partial Updates"},"t":["Partial updates avoid the need to send full representations of data on\n    updates, especially for People and App Data. The primary use case is when a\n    client has retrieved a full representation and subsequently wishes to send\n    a small update to a server. In the most general case, the client may have a\n    series of small updates (e.g., changing tags on a large number of contacts)\n    scattered across many resources. To accomplish these partial updates we\n    will take advantage of the \"fields\" parameter.","When the \"fields\" parameter is specified on a url, only those fields\n    will be looked at when updating an object. If a field is in the parameter\n    list but not part of the post, that would be considered a removal of that\n    field. If the field is in the post but not in the parameter list a 400 bad\n    request error will be returned. If a field is in both places then it will\n    be updated normally."]},{"@attributes":{"title":"Example"},"t":["This example demonstrates the use of etags to detect an incompatible\n    update to the profile of the user identified in the auth token. The request\n    is attempting to update the 'books' field and passes the etag the client\n    received when it retrieved the person object prior to update. The etag is\n    added to the update request shown below but an intervening update from\n    another client has made the change incompatible and so the update is\n    rejected.","Notes: \n    \n    "]}]}]},"back":{"references":[{"@attributes":{"title":"Discussion"},"comment":{},"reference":[{"@attributes":{"anchor":"Issue-1142","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1142"},"front":{"title":"Fix Gadget XSD"}},{"@attributes":{"anchor":"Issue-1138","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1138"},"front":{"title":"OAuth 2.0 Support"}},{"@attributes":{"anchor":"Issue-1211","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1211"},"front":{"title":"Content Upload spec consistency check\/cleanup"}},{"@attributes":{"anchor":"Issue-1201","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1201"},"front":{"title":"Allow a 403 FORBIDDEN response for insufficient privileges"}},{"@attributes":{"anchor":"Issue-1230","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1230"},"front":{"title":"Align the REST core and social API server spec to follow the core data spec for Collection type wrapped with \"list\" property"}},{"@attributes":{"anchor":"Issue-1326","target":"http:\/\/code.google.com\/p\/opensocial-resources\/issues\/detail?id=1326"},"front":{"title":"Response codes using REST protocol"}}]},{"reference":[{"@attributes":{"anchor":"RFC20"},"front":{"title":"ASCII format for Network Interchange"},"seriesInfo":{"@attributes":{"name":"RFC","value":"20"}}},{"@attributes":{"anchor":"RFC2119"},"front":{"title":"Key words for use in RFCs to Indicate Requirement Levels","author":{"@attributes":{"initials":"S.","surname":"Bradner","fullname":"Scott Bradner"},"organization":"Harvard University"},"date":{"@attributes":{"month":"March","year":"1997"}}},"seriesInfo":{"@attributes":{"name":"RFC","value":"2119"}}},{"@attributes":{"anchor":"RFC2234"},"front":{"title":"Augmented BNF for Syntax Specifications: ABNF"},"seriesInfo":{"@attributes":{"name":"RFC","value":"2234"}}},{"@attributes":{"anchor":"RFC2606"},"front":{"title":"Reserved Top Level DNS Names","author":[{"@attributes":{"initials":"D.","surname":"Eastlake","fullname":"Donald E. Eastlake 3rd"},"organization":"IBM"},{"@attributes":{"initials":"A.","surname":"Panitz","fullname":"Aliza R. Panitz"}}],"date":{"@attributes":{"month":"June","year":"1999"}}},"seriesInfo":{"@attributes":{"name":"RFC","value":"2606"}}},{"@attributes":{"anchor":"RFC2616"},"front":{"title":"Hypertext Transfer Protocol -- HTTP\/1.1"},"seriesInfo":{"@attributes":{"name":"RFC","value":"2616"}}},{"@attributes":{"anchor":"RFC3986"},"front":{"title":"Uniform Resource Identifier (URI): Generic Syntax"},"seriesInfo":{"@attributes":{"name":"RFC","value":"3986"}}},{"@attributes":{"anchor":"RFC4287"},"front":{"title":"The Atom Syndication Format","author":[{"@attributes":{"initials":"M.","surname":"Nottingham","fullname":"Mark Nottingham"}},{"@attributes":{"initials":"R.","surname":"Sayre","fullname":"Robert Sayre"}}],"date":{"@attributes":{"month":"December","year":"2005"}}},"seriesInfo":{"@attributes":{"name":"RFC","value":"4287"}}},{"@attributes":{"anchor":"RFC4627"},"front":{"title":"The application\/json Media Type for JavaScript Object Notation (JSON)\n"},"seriesInfo":{"@attributes":{"name":"RFC","value":"4627"}}},{"@attributes":{"anchor":"RFC5023"},"front":{"title":"The Atom Publishing Protocol","author":[{"@attributes":{"initials":"J.","surname":"Gregorio","fullname":"Joe Gregorio"},"organization":"Google"},{"@attributes":{"initials":"B.","surname":"de hOra","fullname":"Bill de hOra"},"organization":"NewBay Software"}],"date":{"@attributes":{"month":"October","year":"2007"}}},"seriesInfo":{"@attributes":{"name":"RFC","value":"5023"}}},{"@attributes":{"anchor":"Rison","target":"http:\/\/mjtemplate.org\/examples\/rison.html"},"front":{"title":"Rison - Compact Data in URIs"}},{"@attributes":{"anchor":"XSdateTime","target":"http:\/\/www.w3.org\/TR\/xmlschema-2\/#dateTime"},"front":{"title":"XML Schema Part 2: Datatypes Second Edition","author":[{"@attributes":{"initials":"P.V.","surname":"Biron","fullname":"Paul V. Biron"},"organization":"Kaiser Permanente, for Health Level Seven"},{"@attributes":{"initials":"A.","surname":"Malhotra","fullname":"Ashok Malhotra"},"organization":"Microsoft"}],"date":{"@attributes":{"month":"October","year":"2004"}}}},{"@attributes":{"anchor":"JSON-RPC","target":"http:\/\/groups.google.com\/group\/json-rpc\/web\/json-rpc-1-2-proposal?pli=1"},"front":{"title":"JSON-RPC 2.0 Specification proposal","author":{"@attributes":{"surname":"JSON-RPC Working Group","fullname":"JSON-RPC Working Group <json-rpc(at)googlegroups.com>"},"0":"\n             "},"date":{"@attributes":{"month":"November","year":"2008"}}}},{"@attributes":{"anchor":"XML-RPC-Introspection","target":"http:\/\/xmlrpc-c.sourceforge.net\/introspection.html"},"front":{"title":"XML-RPC Introspection","author":{"@attributes":{"surname":"opensocial-and-gadgets-spec@googlegroups.com","fullname":"OpenSocial and Gadgets Specification Group"}},"date":{"@attributes":{"month":"January","year":"2000"}}}},{"@attributes":{"anchor":"OAuth-Core-1.0","target":"http:\/\/oauth.net\/core\/1.0\/"},"front":{"title":"OAuth Core 1.0","author":[{"@attributes":{"initials":"M.","surname":"Atwood","fullname":"Mark Atwood"}},{"@attributes":{"initials":"R. M.","surname":"Conlan","fullname":"Richard M. Conlan"},"organization":"Google"},{"@attributes":{"initials":"B.","surname":"Cook","fullname":"Blaine Cook"},"organization":"Twitter"},{"@attributes":{"initials":"L.","surname":"Culver","fullname":"Leah Culver"},"organization":"Pownce"},{"@attributes":{"initials":"K.","surname":"Elliott-McCrea","fullname":"Kellan Elliott-McCrea"},"organization":"Flickr"},{"@attributes":{"initials":"L.","surname":"Halff","fullname":"Larry Halff"},"organization":"ma.gnolia"},{"@attributes":{"initials":"E.","surname":"Hammer-Lahav","fullname":"Eran Hammer-Lahav"}},{"@attributes":{"initials":"B.","surname":"Laurie","fullname":"Ben Laurie"},"organization":"Google"},{"@attributes":{"initials":"C.","surname":"Messina","fullname":"Chris Messina"}},{"@attributes":{"initials":"J.","surname":"Panzer","fullname":"John Panzer"}},{"@attributes":{"initials":"S.","surname":"Quigley","fullname":"Sam Quigley"},"organization":"Twitter"},{"@attributes":{"initials":"D.","surname":"Recordon","fullname":"David Recordon"},"organization":"six apart"},{"@attributes":{"initials":"E.","surname":"Sandler","fullname":"Eran Sandler"},"organization":"Yedda"},{"@attributes":{"initials":"J.","surname":"Sergent","fullname":"Jonathan Sergent"},"organization":"ma.gnolia"},{"@attributes":{"initials":"B.","surname":"Slesinsky","fullname":"Brian Slesinsky"}},{"@attributes":{"initials":"A.","surname":"Smith","fullname":"Andy Smith"},"organization":"Jaiku"}],"date":{"@attributes":{"month":"December","year":"2007"}}}},{"@attributes":{"anchor":"OAuth-Consumer-Request-1.0-Draft-1","target":"http:\/\/oauth.googlecode.com\/svn\/spec\/ext\/consumer_request\/1.0\/drafts\/1\/spec.html"},"front":{"title":"OAuth Consumer Request 1.0 Draft 1","author":{"@attributes":{"initials":"E.","surname":"Hammer-Lahav","fullname":"Eran Hammer-Lahav"}},"date":{"@attributes":{"month":"December","year":"2007"}}}},{"@attributes":{"anchor":"draft-ietf-oauth-v2-22","target":"http:\/\/tools.ietf.org\/html\/draft-ietf-oauth-v2-22"},"front":{"title":"The OAuth 2.0 Authorization Protocol","author":[{"@attributes":{"initials":"E.","surname":"Hammer-Lahav","fullname":"Eran Hammer-Lahav"},"organization":"Yahoo !"},{"@attributes":{"initials":"D.","surname":"Recordon","fullname":"David"},"organization":"Facebook"},{"@attributes":{"initials":"D.","surname":"Hardt","fullname":"Dick"},"organization":"Microsoft"}],"date":{"@attributes":{"month":"September","year":"2011"}}}},{"@attributes":{"anchor":"Core-Data","target":".\/Core-Data.xml"},"front":{"title":"OpenSocial Core Data Specification","author":{"@attributes":{"fullname":"OpenSocial and Gadgets Specification Group <opensocial-and-gadgets-spec@googlegroups.com>"},"0":"\n     "},"date":{"@attributes":{"month":"August","year":"2011"}}}},{"@attributes":{"anchor":"Social-Data","target":".\/Social-Data.xml"},"front":{"title":"OpenSocial Social Data Specification","author":{"@attributes":{"fullname":"OpenSocial and Gadgets Specification Group <opensocial-and-gadgets-spec@googlegroups.com>"},"0":"\n     "},"date":{"@attributes":{"month":"August","year":"2011"}}}}]}],"section":{"@attributes":{"title":"XML format XSD","anchor":"XML_format_XSD"},"t":{"xref":["Discussion","Discussion"]},"figure":{"artwork":"\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<xs:schema xmlns:tns=\"http:\/\/ns.opensocial.org\/2008\/opensocial\"\n  elementFormDefault=\"qualified\"\n  targetNamespace=\"http:\/\/ns.opensocial.org\/2008\/opensocial\"\n  xmlns:xs=\"http:\/\/www.w3.org\/2001\/XMLSchema\">\n\n  <xs:element name=\"response\">\n    <xs:complexType>\n      <xs:choice>      \n        <xs:element name=\"entry\" type=\"xs:anyType\" \/>\n        <xs:group ref=\"tns:collection\" \/>\n        <xs:element name=\"invalidationKeys\" type=\"tns:InvalidationKeys\" \/>\n      <\/xs:choice>\n    <\/xs:complexType>\n  <\/xs:element>    \n\n  <xs:group name=\"collection\">        \n    <xs:sequence>\n      <xs:element name=\"itemsPerPage\" type=\"xs:int\" \/>\n      <xs:element name=\"startIndex\" type=\"xs:long\" \/>\n      <xs:element name=\"totalResults\" type=\"xs:long\" \/>\n      <xs:element name=\"filtered\" type=\"xs:boolean\" \/>\n      <xs:element name=\"sorted\" type=\"xs:boolean\" \/>\n      <xs:element name=\"updatedSince\" type=\"xs:boolean\" \/>\n      <xs:element name=\"list\" type=\"xs:anyType\" minOccurs=\"0\" maxOccurs=\"1\" \/>\n        <xs:element name=\"entry\" type=\"xs:anyType\" minOccurs=\"0\" maxOccurs=\"unbounded\" \/>\n      <\/xs:element>\n    <\/xs:sequence>\n  <\/xs:group>        \n\n  <xs:complexType name=\"InvalidationKeys\">\n    <xs:sequence>\n      <xs:element name=\"invalidationKey\" type=\"xs:string\" maxOccurs=\"unbounded\" \/>\n    <\/xs:sequence>\n  <\/xs:complexType>\n\n<\/xs:schema>\n"}}}}