Retrieving non-entities with REST data services

The REST data service allows you to retrieve more than only entities, such as entity collections and properties.

Retrieve an entity collection

A RetrieveEntitySet Request can be used by a client to retrieve a set of eXtreme Scale entities. The entities are represented as an Atom Feed Document or JSON array in the response payload. For more details on the RetrieveEntitySet protocol defined in WCF Data Services, refer to MSDN: RetrieveEntitySet Request.

The following RetrieveEntitySet request example retrieves all the Order entities associated with the Customer('IBM') entity. Only orders 5000 and 5001 are displayed here.

AtomPub

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')/orders
Request Header: Accept: application/atom+xml
Request Payload: None
Response Header: Content-Type: application/atom+xml

Response Payload:

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base = "http://localhost:8080/wxsrestservice/restservice"
			xmlns:d = "http://schemas.microsoft.com/ado/2007/08/dataservices"
			xmlns:m = "http://schemas.microsoft.com/ado/2007/08/dataservices/
			metadata" xmlns =	"http://www.w3.org/2005/Atom">
    <title type = "text">Order</title>
    <id>http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/
					Order</id>
    <updated>2009-12-16T22:53:09.062Z</updated>
    <link rel = "self" title = "Order" href = "Order"/>
    <entry>
        <category term = "NorthwindGridModel.Order" scheme = "http://
						schemas.microsoft.com/
						ado/2007/08/dataservices/scheme"/>
        <id>http://localhost:8080/wxsrestservice/restservice/
						NorthwindGrid/Order(orderId=5000,customer_customerId=
						'IBM')</id>
        <title type = "text"/>
        <updated>2009-12-16T22:53:09.062Z</updated>
        <author>
            <name/>
        </author>
        <link rel = "edit" title = "Order" href = "Order(orderId=5000,
						customer_customerId='IBM')"/>
        <link rel = "http://schemas.microsoft.com/ado/2007/08/
						dataservices/related/customer"
						type =	"application/atom+xml;type=entry"
						title = "customer" href = "Order(orderId=5000,
						customer_customerId='IBM')/customer"/>
        <link rel = "http://schemas.microsoft.com/ado/2007/08/
						dataservices/related/orderDetails"
						type = "application/atom+xml;type=feed"
						title = "orderDetails" href = "Order(orderId=5000,
									customer_customerId='IBM')/
								orderDetails"/>
        <content type = "application/xml">
            <m:properties>
                <d:orderId m:type = "Edm.Int32">5000</d:orderId>
                <d:customer_customerId>IBM</d:customer_customerId>
                <d:orderDate m:type = "Edm.DateTime">2009-12-16T19:
										46:29.562</d:orderDate>
                <d:shipCity>Rochester</d:shipCity>
                <d:shipCountry m:null = "true"/>
                <d:version m:type = "Edm.Int32">0</d:version>
            </m:properties>
        </content>
    </entry>
    <entry>
        <category term = "NorthwindGridModel.Order" scheme = "http://
						schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
        <id>http://localhost:8080/wxsrestservice/restservice/
						NorthwindGrid/Order(orderId=5001,	customer_customerId='IBM')
				</id>
        <title type = "text"/>
        <updated>2009-12-16T22:53:09.062Z</updated>
        <author>
            <name/>
        </author>
        <link rel = "edit" title = "Order" href = "Order(orderId=5001,
							customer_customerId='IBM')"/>
        <link rel = "http://schemas.microsoft.com/ado/2007/08/
							dataservices/related/customer"
							type =	"application/atom+xml;type=entry"
							title = "customer" href = "Order(orderId=5001,
									customer_customerId='IBM')/customer"/>
        <link rel = "http://schemas.microsoft.com/ado/2007/08/
									dataservices/related/orderDetails"
							type = "application/atom+xml;type=feed"
							title = "orderDetails" href = "Order(orderId=5001,
									customer_customerId='IBM')/orderDetails"/>
        <content type = "application/xml">
            <m:properties>
                <d:orderId m:type = "Edm.Int32">5001</d:orderId>
                <d:customer_customerId>IBM</d:customer_customerId>
                <d:orderDate m:type = "Edm.DateTime">2009-12-16T19:50:
										11.125</d:orderDate>
                <d:shipCity>Rochester</d:shipCity>
                <d:shipCountry m:null = "true"/>
                <d:version m:type = "Edm.Int32">0</d:version>
            </m:properties>
        </content>
    </entry>
</feed>

Response Code: 200 OK

JSON

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')/orders
Request Header: Accept: application/json
Request Payload: None
Response Header: Content-Type: application/json

Response Payload:

{"d":[{"__metadata":{"uri":"http://localhost:8080/wxsrestservice/
			restservice/NorthwindGrid/Order(orderId=5000,
			customer_customerId='IBM')",
"type":"NorthwindGridModel.Order"},
"orderId":5000,
"customer_customerId":"IBM",
"orderDate":"\/Date(1260992789562)\/",
"shipCity":"Rochester",
"shipCountry":null,
"version":0,
"customer":{"__deferred":{"uri":"http://localhost:8080/
			wxsrestservice/restservice/NorthwindGrid/Order(orderId=
			5000,customer_customerId='IBM')/customer"}},
"orderDetails":{"__deferred":{"uri":"http://localhost:8080/
			wxsrestservice/restservice/NorthwindGrid/Order(orderId=
			5000,customer_customerId='IBM')/orderDetails"}}},
{"__metadata":{"uri":"http://localhost:8080/wxsrestservice/
					restservice/NorthwindGrid/
			Order(orderId=5001,
			customer_customerId='IBM')",
"type":"NorthwindGridModel.Order"},
"orderId":5001,
"customer_customerId":"IBM",
"orderDate":"\/Date(1260993011125)\/",
"shipCity":"Rochester",
"shipCountry":null,
"version":0,
"customer":{"__deferred":{"uri":"http://localhost:8080/
			wxsrestservice/restservice/NorthwindGrid/Order(orderId=
			5001,customer_customerId='IBM')/customer"}},
"orderDetails":{"__deferred":{"uri":"http://localhost:8080/
			wxsrestservice/restservice/NorthwindGrid/Order(orderId=
			5001,customer_customerId='IBM')/orderDetails"}}}]}

Response Code: 200 OK

Retrieve a property

A RetrievePrimitiveProperty request can be used to get the value of a property of an eXtreme Scale entity instance. The property value is represented as XML format for AtomPub requests and a JSON object for JSON requests in the response payload. For more details on RetrievePrimitiveProperty request, refer to MSDN: RetrievePrimitiveProperty Request.

The following RetrievePrimitiveProperty request example retrieves the contactName property of the Customer('IBM') entity.

AtomPub

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')/contactName
Request Header: Accept: application/xml
Request Payload: None
Response Header: Content-Type: application/atom+xml

Response Payload:

<contactName xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
    John Doe
</contactName>

Response Code: 200 OK

JSON

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')/contactName
Request Header: Accept: application/json
Request Payload: None
Response Header: Content-Type: application/json
Response Payload: {"d":{"contactName":"John Doe"}}
Response Code: 200 OK

Retrieve a property value

A RetrieveValue request can be used to get the raw value of a property on an eXtreme Scale entity instance. The property value is represented as a raw value in the response payload. If the entity type is one of the following, then the media type of the response is “text/plain." Otherwise the response' media type is “application/octet-stream." These types are:

Java™ primitive types and their respective wrappers
java.lang.String
byte[]
Byte[]
char[]
Character[]
enums
java.math.BigInteger
java.math.BigDecimal
java.util.Date
java.util.Calendar
java.sql.Date
java.sql.Time
java.sql.Timestamp

For more details on the RetrieveValue request, refer to MSDN: RetrieveValue Request.

The following RetrieveValue request example retrieves the raw value of the contactName property of the Customer('IBM') entity.

Request Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')/contactName/$value
Request Header: Accept: text/plain
Request Payload: None
Response Header: Content-Type: text/plain
Response Payload: John Doe
Response Code: 200 OK

Retrieve a link

A RetrieveLink Request can be used to get the link(s) representing a to-one association or to-many association. For the to-one association, the link is from one eXtreme Scale Entity instance to another, and the link is represented in the response payload. For the to-many association, the links are from one eXtreme Scale Entity instance to all others in a specified eXtreme Scale entity collection, and the response is represented as a set of links in the response payload. For more details on RetrieveLink request, refer to MSDN: RetrieveLink Request.

Here is a RetrieveLink request example. In this example, we retrieve the association between entity Order(orderId=5000,customer_customerId='IBM') and its customer. The response shows the Customer entity URI.

AtomPub

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Order(orderId=5000,customer_customerId='IBM')/$links/customer
Request Header: Accept: application/xml
Request Payload: None
Response Header: Content-Type: application/xml

Response Payload:

<?xml version="1.0" encoding="utf-8"?>
<uri>http://localhost:8080/wxsrestservice/restservice/
			NorthwindGrid/Customer('IBM')</uri>

Response Code: 200 OK

JSON

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Order(orderId=5000,customer_customerId='IBM')/$links/customer
Request Header: Accept: application/json
Request Payload: None
Response Header: Content-Type: application/json
Response Payload: {"d":{"uri":"http:\/\/localhost:8080\/wxsrestservice\/restservice\/NorthwindGrid\/Customer('IBM')"}}

Retrieve service metadata

A RetrieveServiceMetadata Request can be used to get the conceptual schema definition language (CSDL) document, which describes the data model associated with the eXtreme Scale REST data service. For more details on RetrieveServiceMetadata request, refer to MSDN: RetrieveServiceMetadata Request.

Retrieve service document

A RetrieveServiceDocument Request can be used to retrieve the Service Document describing the collection of resources exposed by the eXtreme Scale REST data service. For more details on RetrieveServiceDocument request, refer to MSDN: RetrieveServiceDocument Request.