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 type | Defaults to |
|---|---|
| Application/json | Application/json;vnd.sage=sdata |
| Application/xml | Application/atom+xml |
| No media type specified | Use 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 operation | HTTP Verb | Compliance level |
|---|---|---|
| Read | GET | SHOULD |
| Update - full contents | PUT | MAY |
| Update - partial contents | PATCH | MAY |
| Create operation | POST | MAY |
| Delete operation | DELETE | MAY |
| Queries | GET | SHOULD: support of the basic query set.
Properties usable in queries are at least:
|
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.