Callback for notification after async invocation of Create, Update, Delete and Service Operations

Introduce a new prefer header named 'odata.callback' which can be used in combination with either the respond-async or odata.track-changes preferences. The following is the text proposed to be added to the protocol document: There are two scenarios in which links are being returned which are then later used to retrieve information, following a previous request, from the service. These are: • The service has provided a URL to a status monitor resource in the Location header of a 202 accepted response, to a request which specified the respond-async preference in the prefer header. • The service has provided a delta-link in a response to a request in which the client expressed his desire to be able to track subsequent changes, by specifying the odata.track-changes preference in the prefer header. To prevent having to poll the service for updates, not knowing if the request has finished in the async case or changes have become available in the delta-link case, the client MAY specify the odata.callback preference requesting the service to notify the consumer when the respective event has occurred. The odata.callback preference can therefore be used: • when requesting asynchronous processing of a request, using the respond-async preference • on a GET request to a delta-link If the service honors the odata.callback preference it MUST include odata.callback in the Preference-Applied response header. If used on an asynchronous request the respond-async preference also MUST be included in the Preference-Applied response header. For asynchronous requests the odata.callback preference, when applied, will result in the service invoking the specified service endpoint once the service has finished processing the request. The status monitor resource, returned in the Location Header of the previously returned 202 accepted response, can then be used to retrieve the results of the asynchronously executed request. Adding the odata.callback preference to a GET request to a delta-link at the time where there are no changes available and which also has the odata.track-changes preference specified, when applied, results in a 202 Accepted response to the GET request with a location header specifying the delta-link to be used to check for future updates. The service will invoke the specified service endpoint once new changes become available. Combining both the respond-async and odata.callback preference on a GET request to a delta-link, which also has the odata.track-changes preference specified, might influence the response in a couple of ways. If the service decides to process the request synchronously, and no updates are available, then the response is the same as if the respond-async hadn't been specified and results in a response as described above. If the service ends up processing the request asynchronously then it response with a 202 accepted response specifying the URL to the status monitor resources as it would have with any other asynchronous request. Once the service has finished processing the asynchronous request to the delta-link resource, it will invoke the specified service endpoint if updates are available. If however no updates are available it SHOULD hold of notifying the consumer until updates become available. Once notified, the consumer will use the status monitor resource, returned in the previously returned 202 accepted response, to retrieve the results of the asynchronously executed request against the delta-link resource. In case no updates were available after processing the initial request, the result will contain no updates and the consumer will use the delta-link contained in the result to retrieve the updates that have become available since. The odata.callback preference MUST specify a URL, using a parameter named 'url', to a service endpoint which the service needs to invoke to notify the consumer. A service supporting callback SHOULD at least support the HTTP protocol. If the URL specifies references an HTTP endpoint, the service executes a HTTP GET request against the specified URL to notify the consumer. If a service support additional, non HTTP, protocols it SHOULD advertise the supported protocols using the capability annotation "CallbackProtocols" defined in []. The consumer could reuse the same URL as the service end-point for notification. In case the same service endpoint is being used the service MAY collate those requests for notification and therefore effectively ignore the previous request for a notification. The consumer MUST be prepared to deal with situations in which it is being notified up to as many times as it asked to be notified and not presume that the service collates notifications even if it specified the same URL. The Capability Annotation for Callback Protocols is specified as follows: <Term Name="CallbackProtocols" Type="Collection(Capabilities.CallbackProtocolType)" AppliesTo="EntityContainer EntitySet"> <Annotation Term="Core.Description" String="Lists all types of supported callback endpoints for this container or entity set" /> </Term> <ComplexType Name="CallbackProtocolType"> <Property Name="Id" Type="Edm.String"> <Annotation Term="Core.Description" String="Protcol Identifier" /> </Property> <Property Name="UrlTemplate" Type="Edm.String"> <Annotation Term="Core.Description" String="URL Template including parameters. Parameters are enclosed in curly braces {} as defined in RFC6570" /> </Property> <Property Name="DocumentationUrl" Type="Edm.String" Nullable="true"> <Annotation Term="Core.Description" String="Human readable description of the meaning of the URL Template parameters" /> <Annotation Term="Core.IsURL"></Annotation> </Property> </ComplexType> Apart from requiring the prefer-async preference to be returned in the Preference-Applied response header for the use with notifications we propose that the server MUST always return the prefer-async preference in Preference-Applied response header if applied to make it consistent across its use in OData.

https://www.oasis-open.org/committees/download.php/49613/odata-v4.0-wd02-part1-protocol-2013-06-19.docx https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/vocabularies/Org.OData.Core.V1.xml?rev=377 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/vocabularies/Org.OData.Capabilities.V1.xml?rev=379 https://www.oasis-open.org/committees/download.php/49614/odata-v4.0-wd02-part2-url-conventions-2013-06-19.docx https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-construction-rules.txt?rev=380 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-testcases.xml?rev=380 https://www.oasis-open.org/committees/download.php/49615/odata-v4.0-wd02-part3-csdl-2013-06-19.docx https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/edmx.xsd?rev=357 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/edm.xsd?rev=377 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/MetadataService.edmx?rev=374 https://www.oasis-open.org/committees/download.php/49611/odata-atom-format-v4.0-wd02-2013-06-19.docx https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/metadata.xsd?rev=382 https://www.oasis-open.org/committees/download.php/49612/odata-json-format-v4.0-wd02-2013-06-19.docx