Retrieve requests with the REST data service

A RetrieveEntity Request is used by a client to retrieve an eXtreme Scale entity. The response payload contains the entity data in AtomPub or JSON format. Also, the system operator $expand can be used to expand the relations. The relations are represented in line within the data service response as an Atom Feed Document, which is a to-many relation, or an Atom Entry Document which is a to-one relation.

Tip: For more details on the RetrieveEntity protocol defined in WCF Data Services, refer to MSDN: RetrieveEntity Request.

Retrieving an entity

The following RetrieveEntity example retrieves a Customer entity with key.

AtomPub

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

Response Payload:

<?xml version="1.0" encoding="ISO-8859-1"?>
<entry 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">

<category term = "NorthwindGridModel.Customer" scheme = "http://
schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<id>http://localhost:8080/wxsrestservice/restservice/
			NorthwindGrid/Customer('ACME')</id>
    <title type = "text"/>
    <updated>2009-12-16T19:52:10.593Z</updated>
    <author>
        <name/>
    </author>
    <link rel = "edit" title = "Customer" href = "Customer(
					'ACME')"/>
    <link rel = "http://schemas.microsoft.com/ado/2007/08/
					dataservices/related/
orders" type = "application/atom+xml;type=feed" title =
		"orders" href ="Customer('ACME')/orders"/>
    <content type = "application/xml">
        <m:properties>
            <d:customerId>ACME</d:customerId>
            <d:city m:null = "true"/>
            <d:companyName>RoaderRunner</d:companyName>
            <d:contactName>ACME</d:contactName>
            <d:country m:null = "true"/>
            <d:version m:type = "Edm.Int32">3</d:version>
        </m:properties>
    </content>
</entry>

Response Code:
200 OK

JSON

Method
GET
Request URI:
http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('ACME')
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/Customer('ACME')",
			"type":"NorthwindGridModel.Customer"},
			"customerId":"ACME",
			"city":null,
			"companyName":"RoaderRunner",
			"contactName":"ACME",
			"country":null,
			"version":3,
			"orders":{"__deferred":{"uri":"http://localhost:8080/
						wxsrestservice/restservice/
			NorthwindGrid/Customer('ACME')/orders"}}}}

Response Code:
200 OK

Queries

A query can also be used with a RetrieveEntitySet or RetrieveEntity request. A query is specified by the system $filter operator.

For details on the $filter operator, refer to: MSDN: Filter System Query Option ($filter)

The OData protocol supports several common expressions. The eXtreme Scale REST data service supports a subset of the expressions defined in the specification:

Boolean expressions:
- eq, ne, lt, le, gt, ge
- negate
- not
- parenthesis
- and, or
Arithmetic expressions:
- add
- sub
- mul
- div
Primitive literals
- String
- date-time
- decimal
- single
- double
- int16
- int32
- int64
- binary
- null
- byte

The following expressions are not available:

Boolean expressions:
- isof
- cast
Method call expressions
Arithmetic expressions:
- mod
Primitive literals:
- Guid
Member expressions

For a complete list and description of the expressions that are available in Microsoft WCF Data Services, see section 2.2.3.6.1.1 : Common Expression Syntax.

The following example demonstrates a RetrieveEntity request with a query. In this example, all customers whose contact name is “RoadRunner” are retrieved. The only customer which matches this filter is Customer('ACME') as shown in the response payload.

Restriction: This query will only work for non-partitioned entities. If Customer is partitioned, then the key belonging to the customer is required.

AtomPub

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer?$filter=contactName eq 'RoadRunner'
Request Header: Accept: application/atom+xml
Input Payload: None
Response Header: Content-Type: application/atom+xml

Response Payload:

<?xml version="1.0" encoding="iso-8859-1"?>
<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">Customer</title>
	<id>		http://localhost:8080/wxsrestservice/restservice/
			NorthwindGrid/Customer	</id>
	<updated>2009-09-16T04:59:28.656Z</updated>
	<link rel="self" title="Customer" href="Customer" />
	<entry>
		<category term="NorthwindGridModel.Customer"
			scheme="http://schemas.microsoft.com/ado/2007/08/
			dataservices/scheme" />
		<id>
http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/
		Customer('ACME')</id>
		<title type="text" />
		<updated>2009-09-16T04:59:28.656Z</updated>
		<author>
			<name />
		</author>
		<link rel="edit" title="Customer" href="Customer('ACME')" />
		<link
			rel="http://schemas.microsoft.com/ado/2007/08/dataservices/
						related/orders"
			type="application/atom+xml;type=feed" title="orders"
			href="Customer('ACME')/orders" />
		<content type="application/xml">
			  <m:properties>
            <d:customerId>ACME</d:customerId>
            <d:city m:null = "true"/>
            <d:companyName>RoaderRunner</d:companyName>
            <d:contactName>ACME</d:contactName>
            <d:country m:null = "true"/>
            <d:version m:type = "Edm.Int32">3</d:version>
        </m:properties>
		</content>
	</entry>
</feed>

Response Code: 200 OK

JSON

Method: GET
Request URI:
http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer?$filter=contactName eq 'RoadRunner'
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/Customer('ACME')",
			"type":"NorthwindGridModel.Customer"},
			"customerId":"ACME",
			"city":null,
			"companyName":"RoaderRunner",
			"contactName":"ACME",
			"country":null,
			"version":3,
			"orders":{"__deferred":{"uri":"http://localhost:8080/
					wxsrestservice/restservice/NorthwindGrid/
					Customer('ACME')/orders"}}}]}

Response Code: 200 OK

System operator $expand

The system operator $expand can be used to expand associations. The associations are represented in line in the data service response. Multi-valued (to-many) associations are represented as an Atom Feed Document or JSON array. Single-valued (to-one) associations, are represented as n Atom Entry Document or JSON object.

For more details on the $expand system operator, refer to Expand System Query Option ($expand).

Here is an example of using the $expand system operator. In this example, we retrieve the entity Customer('IBM')which has an Orders 5000, 5001 and others associated with it. The $expand clause is set to “orders”, so the order collection is expand as inline in the response payload. Only orders 5000 and 5001 are displayed here.

AtomPub

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')?$expand=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"?>
<entry 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">
<category term = "NorthwindGridModel.Customer" scheme = "http://schemas.

microsoft.com/ado/2007/08/dataservices/scheme"/>
    <id>http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/
				Customer('IBM')</id>
    <title type = "text"/>
    <updated>2009-12-16T22:50:18.156Z</updated>
    <author>
        <name/>
    </author><link rel = "edit" title = "Customer" href =
				"Customer('IBM')"/>
    <link rel = "http://schemas.microsoft.com/ado/2007/08/dataservices/
				related/orders" type = "application/atom+xml;type=feed" title =
				"orders" href = "Customer('IBM')/orders">
        <m:inline>
            <feed>
                <title type = "text">orders</title>
                <id>http://localhost:8080/wxsrestservice/restservice/
									NorthwindGrid/Customer('IBM')/orders</id>
                <updated>2009-12-16T22:50:18.156Z</updated>
                <link rel = "self" title = "orders" href = "Customer
										('IBM')/orders"/>
                <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:50:18.156Z</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:50:18.156Z</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>
        </m:inline>
    </link>
    <content type = "application/xml">
        <m:properties>
            <d:customerId>IBM</d:customerId>
            <d:city m:null = "true"/>
            <d:companyName>IBM Corporation</d:companyName>
            <d:contactName>John Doe</d:contactName>
            <d:country m:null = "true"/>
            <d:version m:type = "Edm.Int32">4</d:version>
        </m:properties>
    </content>						
</entry>

Response Code: 200 OK

JSON

Method: GET
Request URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')?$expand=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/Customer('IBM')",
	"type":"NorthwindGridModel.Customer"},
"customerId":"IBM",
"city":null,
"companyName":"IBM Corporation",
"contactName":"John Doe",
"country":null,
"version":4,
"orders":[{"__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