Program guide > Access data with the REST data service > Request protocols for the REST data service

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.

Retrive 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"  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"  href="Customer('ACME')" />
          <link
              rel="http://schemas.microsoft.com/ado/2007/08/dataservices/
                          related/orders"
              type="application/atom+xml;type=feed" 
              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

Parent topic:

Request protocols for the REST data service

Related reference

Retrive non-entities with REST data services

Insert requests with REST data services

Update requests with REST data services

Delete requests with REST data services

+

Search Tips   |   Advanced Search