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