RESTful web service body format

wcf

I am new to WCF. I am doing some simple RESTful WCF operation contracts. And, I have a question about options for property BodyStyle of attribute class WebInvoke. One option is WebMessageBodyStyle.Bare, and the other is WebMessageBodyStyle.Wrapped.

When should I use Bare?
When should I use Wrapped?

Thank you for your help.

Assume that you have some contract with XML request/response and some simple data contract:

[ServiceContract]
public interface IService
{
    ...
    [OperationContract]
    [WebInvoke(Method = "POST",
        ResponseFormat = WebMessageFormat.Json,
        RequestFormat = WebMessageFormat.Json,
        BodyStyle = WebMessageBodyStyle.Wrapped)]
    Entity DoWork(Entity entity);
    ...
}

[DataContract]
public class Entity
{
    [DataMember]
    public string Name;

    [DataMember]
    public string Value;
}

Depending on the combination of BodyStyle, RequestFormat and ResponseFormat you will have different formats but in general:

JSON and WebMessageBodyStyle.Bare request and response will be:

Request:

{"Name":"name","Value":"value"}

Response:

{"Name":"ResultName:name","Value":"ResultValue:value"}

JSON and WebMessageBodyStyle.Wrapped request and response will be:

Request:

{"entity":{"Name":"name","Value":"value"}}

Response:

{"DoWorkResult":{"Name":"name","Value":"value"}}

Note: you can change default DoWorkResult name to you own:

[return: MessageParameter(Name = "MyResult")]
Entity DoWork(Entity entity);`

so from now this will be:

{"MyResult":{"Name":"name","Value":"value"}}

XML and WebMessageBodyStyle.Bare request and response will be:

Request:

<Entity xmlns="http://schemas.datacontract.org/2004/07/WcfService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Name>name</Name>
   <Value>value</Value>
</Entity>

Response:

<Entity xmlns="http://schemas.datacontract.org/2004/07/WcfService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Name>name</Name>
   <Value>value</Value>
</Entity>

XML and WebMessageBodyStyle.Wrapped request and response will be:

Request:

 <DoWork xmlns="http://tempuri.org/">
   <entity>
      <Name>name</Name>
      <Value>value</Value>
   </entity>
 </DoWork>

Response:

 <DoWorkResponse xmlns="http://tempuri.org/">
   <DoWorkResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <a:Name>name</a:Name>
      <a:Value>value</a:Value>
   </DoWorkResult>
 </DoWorkResponse>

Note: you can also change default DoWorkResult name with the return: MessageParameter

To answer to your question, which WebMessageBodyStyle you should use depends on your needs and there is no golden rule here. For interoperability, one or another format can be sometimes required. But keep in mind about one limitation of bare body style: as there is only one root in XML format and one object in JSON format, only one parameter can be passed to a method. In fact, if you changed a service contract to something like:

[OperationContract]
[WebInvoke(Method = "POST",
    ResponseFormat = WebMessageFormat.Json,
    RequestFormat = WebMessageFormat.Json,
    BodyStyle = WebMessageBodyStyle.Bare)]
Entity DoWork(string id, Entity entity);

a service would throw a exception:

Operation '' of contract '' specifies multiple request body parameters to be serialized without any wrapper elements. At most one body parameter can be serialized without wrapper elements. Either remove the extra body parameters or set the BodyStyle property on the WebGetAttribute/WebInvokeAttribute to Wrapped.

The usage of the wrapped on the operation description simply wraps the request (or the response) in an XML element. For example, in this contract:

[ServiceContract]
public interface ITest
{
    [OperationContract]
    [WebInvoke(BodyStyle = WebMessageBodyStyle.Bare)]
    string Echo(string text);

    [OperationContract]
    [WebInvoke(BodyStyle = WebMessageBodyStyle.Wrapped)]
    string EchoWrapped(string text);

    [OperationContract]
    [WebInvoke(BodyStyle = WebMessageBodyStyle.Wrapped)]
    int Divide(int dividend, int divisor, out int reminder);
}

The input for the Echo operation is simply a element, with the text contained within. Likewise, its response contains a single element with the return of the operation. For the EchoWrapped operation, the input is actually a element, whose child is a element whose child contains the input to the method.

What a service expects for the Echo operation:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">The input</string>

What a service expects for the EchoWrapped operation:

<EchoWrapped xmlns="http://tempuri.org/"><text>Hello wrapped</text></EchoWrapped>

Source: http://social.msdn.microsoft.com/Forums/vstudio/en-US/9db6793b-8db9-479b-825c-e781d023f6c1/bodystylewebmessagebodystylewrapped-with-requestformatwebmessageformatxml-for-post?forum=wcf

RESTful web service body format

Related

Recent Posts