Links
SData Links are JSON objects that provide the information necessary to operate on a resource. 5
SData Links also convey the operational capabilities on a resource. If links are provided for the creation of a resource, the operation-related specifications like canPost (see the SData 1.1 standard, sme.xsd) become redundant. Other capabilities (like canFilter for example) are gathered in the $capabilities metadata element.
This chapter describes in turn:
- The standard SData links; these cover the CRUD operations on a resource.
- The components of an SData link.
- The links to services and queries related to a resource.
The usage of links and the definition of a $links object is OPTIONAL.
Standard links
SData defines the following standard link objects:
| Description | |
|---|---|
| $create | Link used to create a new resource. |
| $delete | Link used to delete an existing resource. |
| $updateFull | Link used to update a resource by providing all its contents. |
| $updatePartial | Link used to update only a selected subset of the properties of a resource. |
| $details | Link used to retrieve a single resource (the response will contain an entry). |
| $list | Link used to retrieve a set of resources (the response will contain a feed). |
| $lookup | Link used to retrieve a set of resources to be used to populate a list of choices. This corresponds to the sdata:lookup defined in the SData 1.1 specification section 6.7. |
| $prototype | Link used to retrieve the prototype associated with a representation - see $prototype object Section for information on prototypes. |
Any of the above links MAY be present within an SData payload.
Link structure
An SData Link object consists of several properties aiming to decouple the consumer from a provider. These are:
| Description | ||
|---|---|---|
| $url | MUST | The URL pointing to a resource. |
| $method | MAY | HTTP method used to operate on the resource. - default : GET |
| $title | SHOULD | Localized label/caption for the link. |
| $id | MAY | MAY be used to identify a link in a specific context. This property MUST be set for prototype links if several prototypes are available for a resource. |
| $body | MAY | The object containing the payload transported to the provider alongside the request. |
| $invocation | MAY | The manner in which the provider should process the request 6. Allowable values are:
|
| $batch | MAY | Expresses the manner of invocations supported in batch by the
provider. Allowable values are:
|
| $request | MAY | Contains either:
An individual parameter object has a unique name and contains the following properties:
|
| $response | MAY |
Contains either
|
| $type | MAY | The SData type(application/json;vnd.sage=sdata) or MIME type of the resource. If omitted, the contract default is returned |
Example: Consider an SData object that exposes links for deletion and update operations. This would be expressed as:
{
"$links": {
"$updateFull": {
"$title": "Update the resource",
"$type": "application/json;vnd.sage=sdata",
"$url": "{$url}",
"$method": "PUT"
},
"$delete": {
"$title": "Delete this resource",
"$type": "application/json;vnd.sage=sdata",
"$url": "{$url}",
"$method": "DELETE"
}
}
}
The URL used is the same with the URL of the resource in this case. The {$url} notation indicates a replacement with a resource value as explained in section Substitution formalism of this document.
Service and query links
Links are used to express services and queries delivered by a provider, as defined in the SData specification section 11 and section 12. In this case, the name of the link object corresponds to the desired query/service.
Examples: The following is the link accessing the createBOM service returning the bill of materials associated with a sales order.
{
"$links": {
"createBOM": {
"$title": "Create Bill of Materials",
"$url": "{$url}/$service/createBOM",
"$method": "POST",
"$response": "{$baseUrl}/$prototypes/createBOM",
"$invocation": "syncOrAsync"
}
}
}
In addition to the URL and appropriate HTTP method, the link indicates the structure of the response (by means of a prototype which is discussed later in this document) as well as the fact that the server may choose whether the service is to be performed in a synchronous or an asynchronous manner.
The following is an example showing an SData query associated with a Products resource kind (described in the SData documentation Example of Named Query):
{
"$links": {
"reOrder": {
"$title": "List of products to be reordered",
"$url": "{$url}/$queries/reorder",
"$method": "GET",
"$request": {
"$properties": {
"family": {
"$title": "product category",
"$type": "sdata/string"
},
"threshold": {
"$title": "minimal in-stock threshold",
"$type": "sdata/integer"
}
}
},
"$response": {
"$type": "sdata/array",
"$item": {
"$properties": {
"productID": {
"$title": "Product ID",
"$type": "sdata/string"
},
"description": {
"$title": "Description",
"$type": "sdata/string"
},
"inStock": {
"$title": "Quantity in stock",
"$type": "sdata/integer"
}
}
}
}
}
}
}
The reOrder named query provides a list of products with stock below a certain threshold value. The specification of the query contains the $request object that contains a description of the two parameters accepted by the query, namely family and threshold. It also describes the structure of the return with the three properties: productID, description and inStock.
5. SData Links are a specific embodiment of Roy Fielding’s hypermedia controls (enabling “Hypermedia as the Engine of Application State” or HATEOAS); Fielding’s indication to REST application designers is that operations (state transfer) be driven by hypertext. Link constructs (as known from HTML and ATOM) appear to be an appropriate means to do this.
6. This should not be confused with client-side AJAX requests. The mechanism corresponds to the sme:invocationMethod described in section 11.4 and 11.5 of the SData 1.1 standard