2.3 Resource Property URL
An SData URL can refer to a property of a resource, as demonstrated by the following example:
http://www.example.com/sdata/myApp/myContract/-/accounts('A001')/postalAddress
| Example | Component Name | Description / Comments |
|---|---|---|
| postalAddress | Property | This element identifies a property of a resource. This URL returns the postal address of the account as an Atom entry. |
SData only allows “relationship properties” in this context - properties that point to another resource or to a collection of related resources. Properties such as postalAddress or contacts are valid in the example, assuming the address and contact are treated as resource kinds by the service. But a property such as accountName would not be allowed, at least in a first version of the SData standard. Although this restriction could be lifted later.
If the relationship refers to a single resource, as in the example which uses a single postal address, the URL returns an Atom entry. If the relationship refers to a collection of resources, the URL returns an Atom feed. Say we had used a property such as addresses in the example. The sme:isCollection schema attribute can be used to determine whether the relationship is a collection or not. See Relationship Definition section for details.
A property is always referred to in the context of a single resource. So, URLs such as accounts(‘A001’)/postalAddress or accounts(‘A001’)/contacts are valid. However, a URL such as accounts/postalAddress is invalid (all postal addresses of all accounts). Note how the URL of the single resource comes first then the property follows.
Properties can be chained, as long as the previous rule is satisfied. So, the following URLs are also valid:
http://www.example.com/sdata/myApp/myContract/-/accounts('A001')/postalAddress/country
http://www.example.com/sdata/myApp/myContract/-/accounts('A001')/addresses(type eq 'postal')/country
SData also puts restrictions on the operations that can be performed on property URLs. GET operations (query/read) are always allowed. However, POST is only allowed on child collections. PUT and DELETE are only allowed on individual child resources. The following table gives some examples:
| URL | Returns | Supported HTTP Methods | Comments |
|---|---|---|---|
| salesOrders('0023')/orderLines | Feed (GET) Entry (POST) | GET, POST | URL refers to the collection of order line resources. POST appends a new order line. |
| salesOrders('0023')/orderLines('1') | Entry | GET, PUT, DELETE | URL refers to a single order line resource. PUT and DELETE are allowed because order lines are child resources of sales orders. |
| salesOrders('0023')/orderLines('1')/product | Entry | GET | URL refers to a single product resource. PUT and DELETE are not allowed because the line/product relationship is a reference, not a parent/child relationship. |
| salesOrders('0023')/orderLines/product | 400 | Invalid URL. The orderLines segment does not identify a single resource, so a property segment can't follow. | |
| salesOrders('0023')/customer | Entry | GET | URL refers to a single customer resource. PUT and DELETE are not allowed because the salesOrder/customer relationship is a reference, not a parent/child relationship. |
| salesOrders('0023')/deliveryDate | 400 | Invalid URL deliveryDate is a value, not a relationship. |
SData providers SHOULD support resource property URLs. If they do so, they MUST comply with the rules above.