1.2 General Principles
REST-style Web Services
SData is a REST-style web services protocol. The main characteristics of the REST approach are:
- Application data is exposed as resources
- Resources are addressed via URLs
- CRUD operations are mapped to HTTP methods (GET, POST, PUT, DELETE)
- Errors are reported as standard HTTP status codes.
- Functionalities like caching, paging, concurrency handling, asynchronous operations, etc. take advantage of HTTP features whenever possible.
REST-style web services is a whole topic in itself and deserves a lot more than such a short enumeration. People who are curious about REST and who would like to dig into the design philosophy behind SData are encouraged to read the “RESTful Web Services” book by Leonard Richardson and Sam Ruby.
External Standards
SData leverages existing web standards whenever possible. The following table gives a list of the standards upon which SData is built:
| Standard | Role in SData |
|---|---|
| HTTP | The foundation of SData, and of RESTful web services in general |
| HTTPS | The secure version of HTTP, for encrypted communications. |
| XML | The markup language behind the two main data formats used by SData: Atom and XSD |
| Atom | The standard “envelope” for SData request and response payloads |
| XML Schema (XSD) | The markup language for SData schemas (metadata) |
| OpenSearch | Protocol elements for paging |
| SLE (Simple List Extensions) | Optional rendering protocol for Internet Explorer. |
Postel’s Law
This wiki describes the SData protocol in a style that mixes informal examples and more formal protocol specifications. The formal material does not cover all possible cases, as this would have led to a very heavy document. There is nevertheless a very important principle that underlies SData’s design and that implementors should follow when they encounter a situation not or incompletely described in the wiki:
Be conservative in what you send, be liberal in what you receive
This principle is known as Postel’s Law. It is a fundamental principle that underlies the design of many protocols.
The practical implications of this principle for implementors of SData providers are the following:
- SData providers should be tolerant (liberal) in the way they process requests received from SData consumers. For example, if some header is missing (Content-Type for example), the provider can usually infer the value of this header from the request (for example application/atom+xml; type=entry if the request is a POST to a resource kind URL). Then the provider should accept the request and process it instead of returning an error. The provider may nevertheless include a warning in its response to inform the consumer that some protocol element was missing from the request.
- SData providers should be strict (conservative) in the way they format their responses to SData consumers. For example, providers should systematically include the right Content-Type header in all the responses that they produce.
Postel’s law also applies to SData consumers, but we cannot assume that all SData consumers will strictly follow all the rules. This is why it is important that SData providers follow Postel’s rule. This maximizes interoperability, even with consumers that do not handle all the subtleties of the protocol.
This does not mean that SData providers should never return errors. They should be tolerant as long as there is no real ambiguity or incoherence in the request. If, for example, the consumer sends a PUT request for a resource that does not exist, the provider should return a 404 Not Found error, it should not treat the PUT as a POST and create a new resource.