Create and Consume RESTFul Service in .NET Framework 4.0

• Download demo - 15.43 KB

About This

I am writing this article to explain creating & consuming RESTFul service using .NET Framework 4.0.

What is Web Services, WCF?

Web Service

Web Service is like components on a Web Server, client application uses this service by calling Hypertext Transfer Protocol (HTTP) requests across the Web. Using ASP.NET, we can create custom Web Services, and call these services from any client applications.

Web Services are platform, programming language independent; they send as well as receive data using Simple Object Access Protocol (SOAP) messages.

WCF

Windows Communication Foundation (WCF) is Microsoft’s combined programming model for building service-oriented architecture (SOA). Using this, the developer can build a secure, reliable, transacted solutions across platforms.

WCF supports concentrated computing where services have isolated consumers. Clients can consume multiple services as well as services can be consumed by multiple clients.

For creating basic application in WCF, please refer to the article “Introduction of Window Communication Foundation”.

What is REST & RESTful?

Representational State Transfer (REST) is introduced by Roy Fielding on 2000; it is an architectural style of large-scale networked software that takes advantage of the technologies and protocols of the World Wide Web. REST illustrate how concentrated data objects, or resources, can be defined and addressed, stressing the easy exchange of information and scalability.

In 2000, Roy Fielding, one of the primary authors of the HTTP specification, wrote a doctoral dissertation titled Architectural Styles and the Design of Network-based Software Architectures.

REST, an architectural style for building distributed hypermedia driven applications, involves building Resource-Oriented Architecture (ROA) by defining resources that implement uniform interfaces using standard HTTP verbs (GET, POST, PUT, and DELETE), and that can be located/identified by a Uniform Resource Identifier (URI).

REST is not tied to any particular technology or platform – it’s simply a way to design things to work like the Web. People often refer to services that follow this philosophy as “RESTful services.” WCF Services which is developed using REST architectural style is known as RESTFul Services.

What is the REST Starter Kit?

The WCF REST Starter Kit is a set of .NET Framework classes and Visual Studio features and templates that enable users to create and access REST-style Windows Communication Foundation (WCF) services. These services are based on the WCF web programming model available in .NET 3.5 SP1. The starter kit also contains the full source code for all features, detailed code samples, and unit tests.

Creating basic RESTFul Service

Step 1

Create a new WCF project using VS2010.

Step 2

Delete the existing IService1.cs & Service1.svc files and create two new files, IRESTService.cs & RESTService.cs.

Step 3

Create the person entity in the IService.cs (it can be created separately) and write a simple member for this entity. For DataContractSerialization decorate this class and member with DataContract & DataMember attributes. See the code below:

[DataContract]
public class Person
{
    [DataMember]
    public string ID;
    [DataMember]
    public string Name;
    [DataMember]
    public string Age;
}    

Person class and its members decorated with [DataContract] & [DataMember] using System.Runtime.Serialization namespace.

• [DataContract] – An entity class which can be DataContractSerializable over the network.
• [Datamember] – Only decorated with [Datamember] property can be serializable & also property of the class must be decorated with [DataContract]

Step 4

Create methods in IRESTService class and interface decorated with [ServiceContract] & its members decorated with [OperationContrat] using System.ServiceModel namespace.

[ServiceContract]
public interface IRestSerivce
{
    [OperationContract]
    Person CreatePerson(Person createPerson);

    [OperationContract]
    List<person> GetAllPerson();

    [OperationContract]
    Person GetAPerson(string id);

    [OperationContract]
    Person UpdatePerson(string id, Person updatePerson);

    [OperationContract]
    void DeletePerson(string id);
}     

• [ServiceContract] - A service contract exposes class or interface to the client applications, which may contain one or more [OperationContract] methods.
• [OperationContract] - Indicates that a method defines an operation that is part of a service contract in an application, i.e., only the method decorated with [OperationContract] is visible for WCF client application and class of this method must be decorated with [ServiceContract].

Step 5

Up to this level, code is similar to that normal WCF services, RESTful services works under HTTP protocol, as there is two important attributes WebGet & WebInvoke (System.ServiceModel.Web namespace) has to include for making this application as RESTful service.

WebGet and WebInvoke

WebGet operation is logically receiving the information from a service operation & it can be called by the REST programming model. The WebGet attribute is applied to a service operation in addition to the OperationContract and associates the operation with a UriTemplate as well as the HTTP protocol Get verb.

WebInvoke operation logically raises a service option & it can be called by the REST programming model. The WebInvoke attribute is applied to a service operation in addition to the OperationContract and associates the operation with a UriTemplate as well as an underlying transport verb that represents an invocation (for example, HTTP POST, PUT, or DELETE). WebInvoke has a property called Method, it allows specifying different types of HTTP methods (POST, PUT or DELETE), and by default Method is POST.

[ServiceContract]
public interface IRestSerivce
{
    //POST operation
    [OperationContract]
    [WebInvoke(UriTemplate = "", Method = "POST")]
    Person CreatePerson(Person createPerson);

    //Get Operation
    [OperationContract]
    [WebGet(UriTemplate = "")]
    List<person> GetAllPerson();
    [OperationContract]
    [WebGet(UriTemplate = "{id}")]
    Person GetAPerson(string id);

    //PUT Operation
    [OperationContract]
    [WebInvoke(UriTemplate = "{id}", Method = "PUT")]
    Person UpdatePerson(string id, Person updatePerson);

    //DELETE Operation
    [OperationContract]
    [WebInvoke(UriTemplate = "{id}", Method = "DELETE")]
    void DeletePerson(string id);
}
     

Please see the modified code for IRESTService interface, WebGet & WebInvoke attributes decorates for methods available in the IRESTService interface.

Person CreatePerson(Person createPerson);
//It is basically insert operation, so WebInvoke HTTP POST is used

List<person> GetAllPerson();
Person GetAPerson(string id);
//These two methods retrieve the information, so WebGet (HTTP Get) is used

Person UpdatePerson(string id, Person updatePerson);
//This method updates the available information, so WebInvoke HTTP PUT is used

void DeletePerson(string id);
//This method deletes the available information, 
//so WebInvoke HTTP DELETE is used

Step 6

Implement the IRESTService in the RESTService class and complete the business requirements. Please see the sample code below:

public class RestSerivce : IRestSerivce
{
    List<person> persons = new List<person>();
    int personCount = 0;

    public Person CreatePerson(Person createPerson)
    {
        createPerson.ID = (++personCount).ToString();
        persons.Add(createPerson);
        return createPerson;
    }
    
    public List<Person> GetAllPerson()
    {
        return persons.ToList();
    }

    public Person GetAPerson(string id)
    {
        return persons.FirstOrDefault(e => e.ID.Equals(id));
    }

    public Person UpdatePerson(string id, Person updatePerson)
    {
        Person p = persons.FirstOrDefault(e => e.ID.Equals(id));
        p.Name = updatePerson.Name;
        p.Age = updatePerson.Age;
        return p;
    }

    public void DeletePerson(string id)
    {
        persons.RemoveAll(e => e.ID.Equals(id));
    }
}

Step 7

We have to make this service able to be run in ASP.NET compatibility mode, for this AspNetCompatibilityRequirements attributes have to decorate with the RESTService class.

[AspNetCompatibilityRequirements
	(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]

[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single)]

public class RESTSerivce : IRestSerivce
{
    //Code Implementation
    //. . . . . .
    // . . . . . .
}

In the above RESTService class additionally decorated with ServiceBehavior attribute, it specifies internal behavior of a service operation.

Step 8

For using this RESTFul service application, this service has to host. So we need to be done below modification for running the RESTService.

Modifying the Web.Cogfig File

Remove all the code inside the <system.servicemodel> tag and insert the code below:

<serviceHostingEnvironment aspNetCompatibilityEnabled="true">
</serviceHostingEnvironment>
    <standardEndpoints>
      <webHttpEndpoint>
        <standardEndpoint name="" helpEnabled="true" 
	automaticFormatSelectionEnabled="true"></standardEndpoint>
      </webHttpEndpoint>
    </standardEndpoints>
  </system.serviceModel>

<serviceHostingEnvironment> tag helps to run the applications in ASP.NET compatibility mode. <standardEndpoints> tag helps to get WebHelp for the RESTFul application.

Add Global.asax File

We can host RESTFul services using Global.asax file using the below code:

 RouteTable.Routes.Add(new ServiceRoute
	("RestService", new WebServiceHostFactory(), typeof(RESTSerivce)));    

Step 9

Run the RESTFulDemo application, it will be open in the explorer and address bar contain the base address of RESTFulDemo service.

http://localhost:XXXX/

Type the Routingprefix name “RestService” (string value given in the global.asax file).

http://localhost:XXXX/RestService - It is basically URI of the Get operation.

http://localhost:XXXX/restservice/help - It displays the help content for RESTFulDemo service.

Still we saw about creating and hosting the RESTFul services, next we have to consume this service, therefore we will see basic application to consume this RESTFulDemo service.

Consuming RESTFul Service

Step 1

Add a new console application to RESTFulDemo solution.

Step 2

do
{
    try
    {
        string content;
        Console.WriteLine("Enter Method:");
        string Method = Console.ReadLine();

        Console.WriteLine("Enter URI:");
        string uri = Console.ReadLine();

        HttpWebRequest req = WebRequest.Create(uri) as HttpWebRequest;
        req.KeepAlive = false;
        req.Method = Method.ToUpper();

        if (("POST,PUT").Split(',').Contains(Method.ToUpper()))
        {
            Console.WriteLine("Enter XML FilePath:");
            string FilePath = Console.ReadLine();
            content = (File.OpenText(@FilePath)).ReadToEnd();

            byte[] buffer = Encoding.ASCII.GetBytes(content);
            req.ContentLength = buffer.Length;
            req.ContentType = "text/xml";
            Stream PostData = req.GetRequestStream();
            PostData.Write(buffer, 0, buffer.Length);
            PostData.Close();
        }

        HttpWebResponse resp = req.GetResponse() as HttpWebResponse;

        Encoding enc = System.Text.Encoding.GetEncoding(1252);
        StreamReader loResponseStream = 
        new StreamReader(resp.GetResponseStream(), enc);

        string Response = loResponseStream.ReadToEnd();

        loResponseStream.Close();
        resp.Close();
        Console.WriteLine(Response);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message.ToString());
    }

    Console.WriteLine();
    Console.WriteLine("Do you want to continue?");
} while (Console.ReadLine().ToUpper() == "Y");

Step 3

Before running the RESTFulDemo application, set multiple startup projects. Please see the below image:

RUN the application. It will run the RESTFulDemo service as well as RESTClient console application.

HTTP GET Operation

It gives the XML output in the console screen.

HTTP POST Operation

This operation creates a new person entity in the service, it can be seen in the browser by HTTP Get operation.

In the above screen, call the URI http://localhost:XXXX/restservice/1, URI ends with person ID (1). It calls the service operation.

[OperationContract]
[WebGet(UriTemplate = "{id}")]
Person GetAPerson(string id);

So it retrieves the person with ID 1.

Please refer to the attached project for detailed code.

Fiddler tool is more useful to test the RESTFul services.

Conclusion

I hope this article helps you to understand basic concept of RESTFul and that the reader is able to code to create & consume RESTFul service. Please let me know your valuable comments.

References

1. http://msdn.microsoft.com/en-us/library/aa738737.aspx
2. http://msdn.microsoft.com/en-us/netframework/dd547388
3. http://msdn.microsoft.com/en-us/library/dd203052.aspx
4. http://msdn.microsoft.com/en-us/library/system.servicemodel.web.webinvokeattribute.aspx
5. http://msdn.microsoft.com/en-us/library/system.servicemodel.web.webgetattribute.aspx