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's response as an Atom Feed Document (to-many relation) or an Atom Entry Document (to-one relation).

Tip: For more details on the RetrieveEntity protocol defined in WCF Data Services, refer to http://msdn.microsoft.com/en-us/library/dd541268(PROT.10).aspx

Retrieving an entity

The following RetrieveEntity example retrieves a Customer entity with key.

AtomPub

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:

http://msdn.microsoft.com/en-us/library/dd541344(PROT.10).aspx

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

The following expressions are not available:

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:

http://msdn.microsoft.com/en-us/library/dd541448%28PROT.10%29.aspx

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: http://msdn.microsoft.com/en-us/library/dd541606(PROT.10).aspx

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