Previous Page Arrow Next Page Arrow

Requesting content by means of media type negotiation

SData 1.x relied solely on the atom+xml format. SData 2.0 introduces support of the JSON format on par with atom+xml, giving applications the freedom to operate in any one or both formats. A consumer can explicitly request one of the supported formats or alternatively, rely upon the default provider response.

Explicit request

The explicit request for a format is achieved by specifying the media type “atom+xml” or “json” within the Accept header of the request or as a query parameter as shown below:

Accept header Atom Accept: application/atom+xml;vnd.sage=sdata
JSON Accept: application/json;vnd.sage=sdata
Format URL parameter Atom …?format=application/atom+xml;vnd.sage=sdata
JSON …?format=application/json;vnd.sage=sdata

Default/implicit request

A contract can (and should) specify the default format it operates on. The default is chosen to service the majority of the incoming requests without additional specification from the consumer. The following defaults are suggested:

Media typeDefaults to
Application/jsonApplication/json;vnd.sage=sdata
Application/xmlApplication/atom+xml
No media type specifiedUse the contract specified default

Contracts not explicitly naming a default format are assumed to have the application/atom+xml default. This ensures consistency with the current SData 1.x implementations.

Operations

The SData 1.x. specification describes the following logical operations:

SData 2.0 logical operations are implemented through HTTP verbs as shown in the table below:

SData operationHTTP VerbCompliance level
ReadGETSHOULD
Update - full contentsPUTMAY
Update - partial contentsPATCHMAY
Create operationPOSTMAY
Delete operationDELETEMAY
QueriesGETSHOULD: support of the basic query set. Properties usable in queries are at least:
  • sdata:key property if one is defined
  • sdata:uuid property if one is defined
MAY for other properties

The PATCH support is a new addition to SData; it supplants the PUT verb usage for partial payloads. The usage of PUT for partial updates is deprecated with SData 2.0. Existing implementations may still use PUT, but should consider switching to PATCH in upcoming releases.


Previous Page Arrow Next Page Arrow