OpenSocial RPC Protocol Specification v0.9

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. Domain name examples use RFC2606.

This proposal defines an RPC alternative to the . The intent is to support 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. It shares the following with the RESTful spec: The JSON/XML format of the OpenSocial data types for 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. It differs from the RESTful spec in the following ways: Conforms to the specification All 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 an RPC for "system.listMethods" to discover the list of available services and operations using conventions defined by XML-RPC Introspection Within a running gadget the address of the RPC endpoint should be available as a Javascript variable (name and mechanism TBD). In general it is expected that a large percentage of consumers will bypass automated discovery and rely on simpy hardcoding references to the endpoints of various popular containers. This document presents all of its examples in the JSON format but the RPC protocol is equally applicable to an XML format. The data structure returned is equivalent in both formats; the only difference is in the encoding of the data. Singular fields are encoded as string key/value pairs in JSON and tags with text content in XML, e.g. "field": "value" and <field>value</field> respectively. Plural fields are encoded as arrays in JSON and repeated tags in XML, e.g. "fields": [ "value1", "value2" ] and<fields>value1</field><fields>value2</field> respectively. Nodes with multiple sub-nodes are represented as objects in JSON and tags with sub-tags in XML, e.g. "field": { "subfield1": "value1", "subfield2": "value2" } and<field><subfield1>value1</subfield1><subfield2> value2</subfield2></field> respectively.

This maps to fetching /people/@me/@self using the RESTful API. Notes: The params groupId and userId are included here for completeness even though they are the default parameter values for the operation. The "method" field identifies both the service "people" and the operation "get" which has the same semantics as an HTTP GET request in the RESTful spec. "json-rpc" as defined in JSON-RPC is not passed in the request but requests MUST be interpreted as if "json-rpc" : "2.0" was supplied. "id" is an optional identifier the caller may choose to associate with the call, this field is propagated to the response. The "result" field in the response is the returned object, in this case an opensocial.Person object. URL addressable equivalent is http://api.example.org/rpc?method=people.get&id=myself&userId=@me&groupId=@self.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <Auth token> Content-Type: application/json { "method" : "people.get", "id" : "myself" "params" : { "userId" : "@me", "groupId" : "@self" } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "myself" "result" : { "id" : "example.org:34KJDCSKJN2HHF0DW20394", "name" : { "unstructured" : "Jane Doe"}, "gender" : "female" } }

This maps to fetching /people/@me/@self & /people/@me/@friends using the RESTful API. Notes: A batch request is detected by examining the request to see if it is a JSON array of requests. Any request id's specified in a batch SHOULD be unique. The request for "myself" succeeded but the one for "myfriends" failed because the OAuth token does not grant access to this resource. The failure of the "friends" request is indicated by the existence of an "error" object which contains a "code" field which uses the numerical value of the HTTP status code UNAUTHORIZED. See JSON-RPC.Error. The batch response elements are returned in an array in the same order as the corresponding batch request elements. The "id" of the corresponding request in the batch request is carried over to the response. In this example parameters are omitted where they match the defaults. If the call has no parameters the "params" field can be omitted completely.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <Auth token> Content-Type: application/json [ { "method" : "people.get", "id" : "myself" }, { "method" : "people.get", "id" : "myfriends" "params: { "groupId" : "@friends" } } ] HTTP/1.x 207 Multi-Status Content-Type: application/json [ { "id" : "myself", "result" : { "id" : "example.org:34KJDCSKJN2HHF0DW20394", "name" : { "unstructured" : "Jane Doe"}, "gender" : "female" } }, { "id" : "myfriends" "error" : { "code" : 401 } } ]

This maps to fetching /people/@me/@self using the 1st auth-token and fetching /people/@me/@friends using the 2nd auth-token with the RESTful API. Notes: The auth token in the header is used for requests which do not specify an "auth" parameter explicitly.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <1st Auth token> Content-Type: application/json [ { "method" : "people.get", "id" : "a9fd76" }, { "method" : "people.get", "id" : "e453a", "params: { "groupId" : "@friends", "auth" : "<2nd Auth token>" } } ] HTTP/1.x 207 Multi-Status Content-Type: application/json [ { "result" : { ... } }, { "result" : { ... } } ]

This example maps to fetching /people/@me/@friends with the RESTful API. Notes: A response that contains a list of information will contain a "list" field in the result. The result will also include details about the number of elements returned in the "list" field as well as information about how to request additional elements using either paging or indexing. The example shown is for a list that is addressed by indexing. Indices are always 0 based, so valid indices in the list are 0..totalResults-1. URL addressable equivalent is http://api.example.org/rpc?method=people.get&id=myfriends&userId=@me&groupId=@friends.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "people.get", "id" : "myfriends" "params: { "userId" : "@me", "groupId" : "@friends" } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "result" : { "totalResults" : 100, "startIndex" : 0, "itemsPerPage" : 10, "list" : [ {..}, {..}, ] } }

This example maps to PUTing or POSTing a set of key-values to /appdata/@me/@self/app12345 with the RESTful API. This is a fairly simple example of an update. Notes: The userId and groupId params are omitted because they match the defaults. The appId param can be omitted if the auth-token used for the call can be used to derive the value for the appId. The return value on success is VOID, represented by an empty JSON structure. URL addressable equivalent is http://api.example.org/rpc?method=appdata.update&id=setMyData&appId=app12345&data.pokes=3&data.lastPoke=2008-02-13T18:30:02Z.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "appdata.update", "id" : "setMyData" "params: { "appId" : "app12345", "data" : { "pokes" : 3, "lastPoke" : "2008-02-13T18:30:02Z" } } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "result" : { } }

This example maps to PUTing an opensocial.Person object /people/@me/@friends with the RESTful API. This example is a use-case not covered by the OpenSocial JS API and is given here to show how additional operations that a container may want to support can be defined within this framework. This effect of this call may be different based on how the container models the social graph. This may be interpreted as send an invite to the specified person to create a bi-drection friend relationship which may be accepted or rejected later. Depending on the semantics of the group the result of the call can vary and the person added may not be immediately visible in a subsequent person.get call on the same group. Notes: The return value on success is VOID, represented by an empty JSON structure. userId & groupId could be omitted as they match the operation default. Shown for completeness. URL addressable equivalent is http://api.example.org/rpc?method=people.create&id=createFriend&userId=@me&groupId=@friends&person.id=example.org:FF256337.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "people.create", "id" : "createFriend" "params: { "userId" : "@me", "groupId" : "@friends", "person" : { "id" : "example.org:FF256337" } } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "result" : { } }

This example maps to POSTing an opensocial.Person object /people/@me/@self with the RESTful API. This example again is not one covered by the OpenSocial JS but may be supported by containers. The example shown 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 inervening 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 choose to omit this data from conflict error responses.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "person.update", "id" : "setMyData" "params: { "userId" : "@me", "groupId" : "@self", "person" : { "etag" : "767ffdef7", "books" : ["The Prince", "Hotel New Hampshire"] } } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "myself", "error" : { "code" : 409 "message" : "Conflict detected", "data" : { "etag" : "8543de12", "books" : ["The Right Stuff", "About a boy"] } } }

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.

Example: <usual headers> Content-type: multipart/form-data; boundary=------------abcdef012345xyZ Content-length: <contentLength> ------------abcdef012345xyZ Content-Disposition: form-data; name="request" [{ "method":"activities.create", "params": { "userId":["@viewer"], "groupId":"@self", "appId":"@app", "activity": { "title": "hello world!", "mediaItems": [ { "mimeType":"image", "url":"@field:image1" } ] } }, "id":"key" } ------------abcdef012345xyZ Content-Disposition: form-data; name="image1" GIF89....<image data> ------------abcdef012345xyZ

This example illustrates how information for users and a static resources can be invalidated using the cache service. The example shows how to specify a user with a global ID (which include the domain of the container) or a relative ID. The static resource in this example is the gadget spec itself, but it could also be an image or message bundle file.

Example: POST /api/rpc HOST opensocial.example.org Content-Type application/json { method : "cache.invalidate", params : { invalidationKeys : [ "example.org:12345", "example.org:4567", "3456778", "http://www.myapp.com/gadgetpec.xml"] } }

In addition to conforming with the JSON-RPC specification for a container to be an OpenSocial RPC provider they MUST conform to the following conventions.

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. All OpenSocial services MUST expose a "get" [TBD query, fetch are valid alternatives] operation. Operations with the names get, create, update and delete should map to the HTTP equivalent operations in the RESTful API of GET, PUT, POST & DELETE.

The names of the RPC services MUST match the names used in the OpenSocial namespace E.g http://ns.opensocial.org/2008/opensocial/messages.

Calls to the RPC endpoint for batch execution MUST only be supported for HTTP POST requests. A batch of RPC's is an ordered array of requests and the return is an ordered array of responses in the same order. I.e

[ <rpc-request1>, <rpc-request2>, ...] -> [ <rpc-response1>, <rpc-response2>, ...] If processing of the entire batch fails, as opposed to a single request within the batch, then the returned value is a single JSON-RPC response object with the appropriate error message and code.

Many service operations return a list of OpenSocial resources. Lists are always returned in the "list" field of the result. Lists can either be the full set of resources or a pageable subset. If the returned list represents the entire set of resources the response is simply:

{ "result" : { "list" : [ ... ] } } If the operation supports random access indexing of the full list it will support the "startIndex" and "count" parameters which control what sublist of the full list is returned. If the response contains a sublist obtained via random access indexing it will have the general form:

{ "result" : { "totalResults" : <total number of elements in the full list>, "startIndex" : <0 based offset in the full-list of the returned sublist>, "itemsPerPage" : <total number of elements in the returned sublist>, "isFiltered" : <boolean indicating if the result honors filter params in the request>, "isUpdatedSince" : <boolean indicating if the result honors the updatedSince param in the request>, "itemsPerPage" : <total number of elements in the returned sublist>, "list" : [ ... the sublist ...] } } The paging mechanisms described here are based on the OpenSearch standard with the additional requirement that all indexes are 0 based.

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 parameter The RPC id is defined by the 'id' query parameter All 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. { "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=value2 This scheme is intentionally verbose and is designed for simple representation of requests with a limited set of parameters. While more compact URL friendly encodings of JSON exist (e.g. ) this encoding seems more suitable for the intended use case. Some examples: { "method" : "people.get", "id" : "myfriends", "params": {"userId" : "@me", "groupId" : "@friends" }} -> http://api.example.org/rpc?method=people.get&id=myfriends&params.userId=@me&params.groupId=@friends

This specification has the same requirements as the RESTful API for authentication and authorization. In addition Containers SHOULD also support a request context compatible with use by a gadget running the OpenSocial JS in the containers UI. When OAuth is used for authorization on a single RPC the OAuth signature uses the URL Addressing representation of the request without the auth param to calculate the signature base string.

We use a hybrid method call syntax to document the operation supported by a service. The types of parameters are described using the same syntax used by the OpenSocial JavaScript documentation. Most parameter defaults are literal values such as "@me" and some are derived from the calling context and have the following definitions: HttpRequest.Authorization - A parsed version of the authorization information stored in the HTTP Authorization header or that is associated with the request in a container specific manner. auth.AppId - The application id is derived from the authorization token if it is available. User Ids - userId parameters to service operations MUST match the format described in http://code.google.com/apis/opensocial/docs/0.8/spec.html#people or MUST be one of the reserved userId placeholders. All containers must support the @me placeholder value which is used to denote the user identified by the authorization token associated with the request. Any userId value that begins with '@' is reserved by the specification for future use. Group Ids - groupId parameters to service operations MAY be a simple string or one of the reserved groupId placeholders. All containers must support the @self & @friends placeholders values. Any groupId value that begins with '@' is reserved by the specification for future use as a placeholder.

The following arguments are supported by each of the exposed services. The parameters startIndex and count are interpreted according to . Parameter Name Description count The 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. filterBy For a collection, return entries filtered by the given field name. filterOp The operation to use when filtering a collection by a field specified in 'filterBy', defaults to "contains". Valid values are 'contains', 'equals', 'startsWith', and 'present'. filterValue The value to use when filtering a collection. For example, { ... filterBy : name, filterOp : startsWith, filterValue : "John" ...} return all items whose name field starts with John. Johnny and John Doe would both be included.) sortOrder Can either be 'ascending' or 'descending', defaults to ascending. Used to sort objects in a collection. fields An array of field names to include in the representation or in the members of a collection. If no fields are specified in the request it is up to the container to decide which fields to return, however, the response MUST always include a minimum set of fields. For people this is [id, name, thumbnailUrl]. For activities this is [id, title]. In place of an array '@all' is accepted to indicate returning all available fields. networkDistance Modifies group-relative requests (@friends, etc.) to include the transitive closure of all friends up to the specified distance away. MAY NOT be honored by the container. startIndex Index into a paged collection. updatedSince 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).

service-name = "people" Operations Summary: Operation Parameters Return get AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self" opensocial.Person or Array.<opensocial.Person> create AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@friends", opensocial.Person person opensocial.Person update AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", opensocial.Person person opensocial.Person delete AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self" void

Retrieve a single person or list of opensocial.Person objects. All AppData for the person or collection of people returned by a given query may be fetched by specifying the field "appdata" in the fields parameter. If only a subset of AppData fields are desired, they may be fetched by specifying "appdata.<fieldname>" for each field that needs to be fetched. Example: Fetching all AppData for the requestor: { "method":"people.get", "params": { "userId":["@me"], "groupId":"@self", "params": { "fields": "appdata" } } } Example: Fetching the AppData keys "key1", and "key2" for the requestor: { "method":"people.get", "params": { "userId":["@me"], "groupId":"@self", "params": { "fields": ["appdata.key1", "appdata.key2"] } } }

Support creating opensocial.Activity objects as the targets of a relationship with the specified user, this is a generalization of many use cases including invitation, contact creation etc. Implementation of this method is not required to be OpenSocial compliant.

Support updating the properties of an opensocial.Person object identified by its relationship to the specified user. Implementation of this method is not required to be OpenSocial compliant.

Support removing the relationship between an opensocial.Person and the specified user. Implementation of this method is not required to be OpenSocial compliant.

service-name = "activities" Operations Summary: Operation Parameters Return get AuthToken auth = HttpRequest.Authorization, String or Array<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array<String> activityIds = [] opensocial.Activity or Array.<opensocial.Activity> create AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, opensocial.Activity activity opensocial.Activity update AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, opensocial.Activity activity opensocial.Activity delete AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, String activityId void

Retrieve one or a list of opensocial.Activity objects.

Support creating opensocial.Activity objects as the targets of a relationship with the specified user, the specifically supported use case is posting a new activity to the stream of a single user i.e activity.create(userId="@me",groupId="@self", <some activity>) Support for other parameterizations is not required to be OpenSocial compliant.

Support updating opensocial.Activity objects as the targets of a relationship with the specified user. Implementation of this method is not required to be OpenSocial compliant.

Support removing the relationship between an opensocial.Activity and the specified user. Implementation of this method is not required to be OpenSocial compliant.

service-name = "appdata" Operations Summary: Operation Parameters Return get AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> keys Map.<String, String> update AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data void delete AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> keys Map.<String, String>

Retrieve a map of key-value pairs for the list of specified keys.

Add or replace key-value pairs stored in a users appdata with the key-vaues in the data parameter.

Remove the specifed keys from a users appdata and returned the values associated with those removed keys.

service-name = "messages" Operations Summary: Operation Parameters Return send AuthToken auth = HttpRequest.Authorization, String userId = "@me", opensocial.Message message void

Sample JSON for Message as one is not defined in the RESTful spec yet. { "recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"], "title" : "You have an invitation from Joe", "body" : "Some content", "type" : "EMAIL" }

Send an opensocial.Message object to its defined recipients.

service-name = "albums" Operations Summary: Operation Parameters Return get AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> id Map.<String, Album> create AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data String update AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data void delete AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> ids void

service-name = "mediaItems" Operations Summary: Operation Parameters Return get AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> id Map.<String, MediaItem> create AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data String update AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data void delete AuthToken auth = HttpRequest.Authorization, String userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> ids void

The cache service is used to manage the resources cached by the container for a given application. service-name = "cache" Operations Summary: Operation Parameters Return invalidate AuthToken auth = HttpRequest.Authorization, Array.<String> invalidationKeys void

The system service is used to introspect the endpoint for the set of available services and operations and for metadata about those services. service-name = "system" Operations Summary: Operation Parameters Return listMethods Array.<String> methodSignatures String methodName Signature methodHelp String methodName Content

Containers MUST implement this operation which takes no parameters and returns an array of all methods supported by the endpoint including the system methods. For a container which only supports read access to people and read and create access for activities the result would be:

["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. The example below is the Signature response for 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 } } 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.

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.

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. Code Meaning -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..-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.

Containers MAY choose to implement an optimistic concurrency scheme for updates. If this facility is supported by the container an "etag" field will be embedded in the updatable object when it is retrieved. When the container receives a request to update an object and an etag is present in the request the container MAY choose to deny the request because it has detected a conflicting update. Containers are free to allow updates even in the presence of conflicting etags at their own discretion but SHOULD document when such behavior is allowed.

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.

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.