REST - REpresentational State Transfer (Introduction ) REST is not a standard but an approach (specification) to developing and providing services on the internet. REST follows an architectural style of web application, like a user progressing through a web application by selecting links which takes him to the next page. REST is based on Resources that are identified by a unique URI. When we conform to the standard or characteristic defined for a service to be REST, we can refer the service to be RESTful. REST does not tie itself to any particular platform, but is currently done on Web with HTTP.
Fundamental Characteristics / Constraints of REST Client Server Separation of Concerns is a principle where the user interface is separated from data storage. Thi s leads to the portability of the user interface across multiple platforms and improves scalability by simplifying server components.
Stateless Each request to the server s erver should contain all the information required to understand and complete the request.
Cacheable The data within a response to a request should be cacheable/ non-cacheable to be used by client at another point of time. This might improve the performance and reduce network traffic.
Layered System Intermediary servers like Proxy servers or Cache servers can be used to improve performance or introduce security.
Uniform Interface A uniform interface (like HTTP GET, POST, DELETE, PUT) is to be used to access a resource. A RESTful Web Service is a collection of the following:
URI
Uniform Resource Identifier - This is a unique way of identifying resources on the network. Every resource on the web is given a unique identifier - a universal identifier (example, URL). All web browsers, servers, applications understand this identifier, which makes it easy to connect and exchange information between one another without any issues.
MIME Type Can be XML, HTML, and JSON.
HTTP Methods HTTP forms a standard way to communicate with resources on the web. GET, PUT, DELETE, POST are some of the common methods to access a resource.
GET Helps to request a specific representation of the resource.
PUT Updates a resource with a specific s pecific representation.
DELETE Deletes a specified resource.
POST Creates a new resource.
Designing RESTful Services The initial steps in designing RESTful based services is to identify the objects (resources) that will be exposed to the outside world and next to map these resources to a URI. We should not focus on designing the methods for an application; instead, we should focus on designing r esources and their URI. There are various data formats which can be used with REST, but XML is easier and mostly used, but JSON is equally being used.
.NET 4 and REST and WCF WCF is not all about building SOAP based services, it's an extensible framework with a common programming model and a totally pluggable communication infrastructure. infrastructure. The basic job of the WCF runtime is to listen for messages from a network location and process those messages and pass them to the application (service). With .NET 4, developing a REST application is an easy task. Microsoft has
provided a REST template which we can use to create new projects, this will create a basic skeleton code for REST. From VS 2010, create a new project, select an online template, and WCF. There are various options displayed, select "WCF REST Service Template 40". Create a class which returns a collection of employee details. Mark the method which we want to call with the attribute[WebGet()]. Collapse | Copy Code
[ServiceContract] [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)] [ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall)] // NOTE: If the service is is renamed, remember to to update the global.asa global.asax.cs x.cs file
public class class Service1 Service1 { // TODO: Implement Implement the collection resource resource // that will contain the SampleItem instances instances
[WebGet(UriTemplate [WebGet(UriTemplate = "" "")] )] public public IList
GetEmployeeDetail() { IList employeeDetail = new new List(); EmployeeDetail empDetail1 = new new EmployeeDetail(); empDetail1.EmployeeIdentifier = 123 123; ; empDetail1.EmployeeName = "Test1" "Test1"; ; empDetail1.ProjectName empDetail1.ProjectName = "NE" "NE"; ; employeeDetail.Add(empDetail1); EmployeeDetail empDetail2 = new new EmployeeDetail(); empDetail2.EmployeeIdentifier = 1234 1234; ; empDetail2.EmployeeName = "Test2" "Test2"; ; empDetail2.ProjectName empDetail2.ProjectName = "NE" "NE"; ; employeeDetail.Add(empDetail2); return return employeeDetail; } } public class EmployeeDetail EmployeeDetail { private string string employeeName; employeeName; private int int employeeId; employeeId; private string string projectName; projectName; public int EmployeeIdentifier EmployeeIdentifier { get { return employeeId; return employeeId; } set { employeeId = value; } } public string EmployeeName EmployeeName { get
{ return employeeName; return employeeName; } set { employeeName employeeName = value; } } public string string ProjectName ProjectName { get { return projectName; return projectName; } set { projectName projectName = value; } } }
Build and run the code. Now access the URL http://localhost:8422/Service1/ . The following XML is returned from the service: Collapse | Copy Code
xmlns:i ="http://www.w3.org/2001/XMLSchema-instance"> 123 Test1 >NE > 1234 Test2 >NE >
Security and REST If you look into the above code, you will noticed the flaw, this s ervice does not have any security aspect built into it. But when we are building services exposing endpoints, the security aspect should be taken care of. RESTful services are just HTTP endpoints, so all security aspects implemented with HTTP (like HTTPS, certificates) can also be implemented with REST. There are two types of hosting services, self hosting Web Services and Web Services hosted with an application server like IIS. In self hosting Web Services, most of the security aspect should be taken care of in the code; on the other hand, while hosted in IIS, the setting in IIS take care of the security.
Setting Endpoint: Security for Self Hosted
Security of the end point is set by the Security property of WebHttpBinding. The Security property is of typeWebHttpSecurity and is used to determine the security mode required by the binding and the type of client credentials it requires. There are two properties of WebHttpSecurity: Mode (of type WebSecurityHttpMode) andTransport (of type HttpTransportSecurity). There are three levels of security that can be specified usingWebHttpSecurityMode: 1. 2. 3.
None Transport TransportCredentialOnly WebHttpBinding.Security.T WebHttpBindi ng.Security.Transport ransport which is of type HttpTransportSecurity helps to authenticate the client. It has these three properties:
ClientCredentialType (of type HttpClientCredentialType) ProxyCredentialType (of type HttpProxyCredentialType) Releam (String ) Values for HttpClientCredentialType can be any one of the following: None, Basic , Digest, NTLM, Windows,Certificate.
Setting Endpoint: Security for Services Deployed on IIS When hosting an endpoint on IIS, use the web.config file to make configuration changes. The configuration can be done for the virtual directory where the service is running. We need to be aware of both the client config and t he virtual directory configuration.
Authorization Once authenticated, the next step is to authorize the client, what they can do and what they can't do. 1.
2.
Impersonation: by impersonating the client, the authorization is delegated to another layer. For example, when a client is trying to insert or update data in to a SQL Server database, SQL Server throws an exception in case the client doesn't have permission, which can be bubbled back to the client. Role based: Implement authorization by restricting access to operations to certain Windows users or groups.
Advantages of REST
Services offered by REST style are easier to consume compared to o ther style services, meaning lower learning curve for the consumer. Supports caching of URI of the service. Components can be deployed independently. Lightweight (consider SOAP which uses WSDL which makes the SOAP protocol a complex service). Simple clients.
Disadvantage of REST The major disadvantage from a developer's perceptive is it does not have metadata. So it requires knowledge of implementation details. On the security aspect, RESTful s ervices depend on the security aspect of HTTP security.
When to Use REST REST can be implemented when we plan to design an application to be used exclusively on the web, and also when we need a quick client integration.
When Not to Use REST When designing an application of service oriented architecture which interconnects many systems and uses many transport channels, it is better to use SOAP. **************************
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; independent; they send as well w ell as receive data using Simple Object Access Protocol (SOAP) messages.
WCF Windows Communication Foundation (WCF) is Microsoft‘s combined programming model fo r 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‖. Web Services
WCF Services
Web Services
WCF Services
Web services were developed for building applications that send and receive messages by using the Simple Object Access Protocol (SOAP) over HTTP. The structure of the messages can be defined using an XML Schema, and a tool is provided to facilitate serializing the messages to and from .NET Framework objects. The technology can automatically generate metadata to describe Web services in the Web Services Description Language (WSDL)
WCF services were developed for building applications to send and recei formats and conveyed by using any transport protocol. Simple Object Ac by default format.The structure of the messages can be defined using an various options for serializing the messages to and from .NET Framework automatically generate metadata to describe applications built using the also provides a tool for generating clients for those applications from th
XmlSerializer
DataContractSerializer
ASP.NET relies on the XmlSerializerto translate data represented by .NET Framework types to XML for transmission to or from a service and to translate data received as XML into .NET Framework objects. Defining the complex data types that an ASP.NET service is to use requires the definition of .NET Framework classes that theXmlSerializer can serialize to and from XML.
The DataContractAttribute signifies that zero or more of a type‘s serialized, while theDataMemberAttribute indicates that a particular serialized. The DataContractAttributecan be applied to a class or s TheDataMemberAttribute can be applied to a field or a property, an which the attribute is applied can be either public or private. Instan the DataContractAttribute applied to them are referred to as data serialized into XML using DataContractSerializer.
The XmlSerializer and the attributes of theSystem.Xml.Serializationnamespace are designed to allow you to map .NET Framework types to any valid type defined in XML Schema, and so they provide for very precise control over how a type is represented in XML.
The DataContractSerializer,DataContractAttribute and Da very little control over how a type is represented in XML. You can only sp names used to represent the type and its fields or properties in the XML, the fields and properties appear in the XML. Everything else about the str represent the .NET type is determined by the DataContractSerializ control over how a type is to be represented in XML, the serialization pro predictable for the DataContractSerializer, and, thereby, easier to
Lesser performance compared with WCF DataContractSerializer .
A practical benefit of the design of the DataContractSerializer is approximately ten percent better performance.
The attributes for use with theXmlSerializer do not indicate which fields or properties of the type t ype are serialized into XML. The XmlSerializer can only translate the public members of a .NET object into XML.
Support for sending messages using not only HTTP, but also TCP and ot ability to switch message protocols with minimal effort. Support for hosti than a Web server. Built-in support for the latest Web services standards ability to easily support new ones. Support for security, transactions and messages using formats other than SOAP.
DataMemberAttribute for use with theDataContractSerialize or properties are serialized. Therefore, data contracts are explicit contrac data that an application is to send and receive. The DataContractSerializer can translate the members of objects access modifiers of those members.
Instances of collection classes c an be serialized The DataContractSerializer is much more likely to be able to seri into XML only if the classes implement either existing .NET type into XML without having to either modify the definitio the IEnumerable orICollection interface. wrapper for it.
Web Services
Classes that implement theIDictionary interface, such asHashtable, cannot be serialized into XML.
WCF Services
It can translate into XML types like Hashtable that implement the IDi
XmlSerializer does not support versioning. The DataContractSerializer incorporates some support for versio XmlSerializer serializes a type by default is DataContractSerializer serializes a type, provided the namespac semantically identical to the XML.
defined.
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 o f the primary authors of the HTTP specification, wrote a doctoral dissertation titled Architectural Styles and the Design of Network-based Software Software Architectures. REST, an architectural style for building distributed hypermedia 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. WCF Services
RESTFul Services
Endpoints have to create for each network protocol
It can be connect over o ver "Web" with HTTP request/response messages.
It works based on the Remote Procedural Call (RPC)
It is working with HTTP's uniform interface
Service Reference has to add in the client applications
No need to add the service reference in the client applications
What is the REST Starter Kit? . NET Framework classes and Visual Studio features and templates The WCF REST Starter Kit is a set of .NET that enable users to create and access REST-style Windows Communication Foundation (WCF) services. These services are based on the WCF web programming model model available in .NET 3.5 SP1. The start er 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. Language
Visual C# or Visual Basic
Target Framework
.NET Framework 4
Installed Templates
WCF
Template
WCF Service Application
Name
RESTFulDemo
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. ForDataContractSerialization decorate this class and member with DataContract & DataMember attributes. See the code below: Collapse | Copy Code
[DataContract] public class class Person Person { [DataMember] public string string ID; ID; [DataMember] public string string Name; Name; [DataMember] public string string Age; Age; }
Person class and its members decorated with [DataContract] & [DataMember] usingSystem.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. Collapse | Copy Code
[ServiceContract] public interface interface IRestSerivce IRestSerivce { [OperationContract] Person CreatePerson(Person CreatePerson(Person createPerson); [OperationContract] List GetAllPerson(); GetAllPerson();
[OperationContract] Person GetAPerson( GetAPerson( string string id); id); [OperationContract] Person UpdatePerson( UpdatePerson( string string id, id, Person updatePerson); [OperationContract] void DeletePerson( DeletePerson( string string id); 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 s ervices 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 OperationContractand associates the operation with a UriTemplate as well as the HTTP protocol Get verb.
s ervice option & it can be called by the REST programming WebInvoke operation logically raises a service model. TheWebInvoke 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 Method is POST. Collapse | Copy Code
[ServiceContract] public interface interface IRestSerivce IRestSerivce { //POST operation operation
[OperationContract] [WebInvoke(UriTemplate [WebInvoke(UriTemplate = "" "", , Method = "POST" "POST")] )] Person CreatePerson(Person CreatePerson(Person createPerson); //Get Operation Operation
[OperationContract] [WebGet(UriTemplate [WebGet(UriTemplate = "" "")] )] List GetAllPerson(); GetAllPerson(); [OperationContract]
[WebGet(UriTemplate [WebGet(UriTemplate = "{id}" "{id}")] )] Person GetAPerson( GetAPerson( string string id); id); //PUT Operation Operation
[OperationContract] [WebInvoke(UriTemplate [WebInvoke(UriTemplate = "{id}" "{id}", , Method = "PUT" "PUT")] )] Person UpdatePerson( UpdatePerson( string string id, id, Person updatePerson); //DELETE Operation Operation
[OperationContract] [WebInvoke(UriTemplate [WebInvoke(UriTemplate = "{id}" "{id}", , Method = "DELETE" "DELETE")] )] void DeletePerson( DeletePerson( string string id); id); }
Please see the modified code for IRESTService interface, WebGet & WebInvoke attributes decorates for methods available in the IRESTService interface. Collapse | Copy Code
Person CreatePerson(Person createPerson); //It is basically basically insert insert operation, operation, so WebInvoke WebInvoke HTTP POST POST is used
List List GetAllPerson(); GetAllPerson(); Person GetAPerson( string string id); id); //These two methods retrieve retrieve the information, information, so WebGet (HTTP (HTTP Get) is used
Person UpdatePerson( UpdatePerson(string string id, id, Person updatePerson); //This method method updates the available available information, information, so WebInvoke WebInvoke HTTP PUT PUT is used
void DeletePerson( void DeletePerson(string string id); id); //This method method deletes the available available information, information, //so WebInvoke WebInvoke HTTP DELETE DELETE is used used
Step 6 Implement the IRESTService in the RESTService class and complete the business requirements. Please see the sample code below: Collapse | Copy Code
public class class RestSerivce RestSerivce : IRestSerivce { List persons = new new List(); int personCount int personCount = 0; public Person CreatePerson(Person createPerson) public Person { createPerson.ID createPerson.ID = (++personCount).ToStrin (++personCount).ToString(); g(); persons.Add(createPerson); return createPerson; createPerson; } public List public List GetAllPerson() { return persons.ToList(); persons.ToList(); }
public Person public Person GetAPerson( string string id) id) { return persons.FirstOrDefault persons.FirstOrDefault(e (e => e.ID.Equals(id)); e.ID.Equals(id)); } public Person public Person UpdatePerson( string string id, id, Person updatePerson) { Person p = persons.FirstOrDefault(e => e.ID.Equals(id)); p.Name = updatePerson.Name; updatePerson.Name; p.Age = updatePerson.Age; updatePerson.Age; return p; return p; } public void DeletePerson( DeletePerson(string string id) id) { persons.RemoveAll(e persons.RemoveAll(e => e.ID.Equals(id)); e.ID.Equals(id)); } }
Step 7 We have to make this service able to be run in ASP.NET compatibility mode, for thisAspNetCompatibilityRequirements attributes have to decorate with the RESTService class. Collapse | Copy Code
[AspNetCompatibilityR [AspNetCompatibilityRequirements equirements (RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)] [ServiceBehavior(Inst [ServiceBehavior(InstanceContextM anceContextMode ode = InstanceContextMode. InstanceContextMode. Single Single)] )] public class class RESTSerivce RESTSerivce : IRestSerivce { //Code Implementation 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 tag and insert the code below: Collapse | Copy Code
tag helps to run the applications in ASP.NET compatibility mode. tag helps to get WebHelp for the RE STFul application.
Add Global.asax File We can host RESTFul services using Global.asax file file using the below code: Collapse | Copy Code
RouteTable.Routes.Add( new ServiceRoute ServiceRoute ("RestService" , new new WebServiceHostFactory(), typeof typeof(RESTSerivce))); (RESTSerivce)));
Step 9 Run the RESTFulDemo application , it will be open in the explorer and address bar contain the base address RESTFulDemo service. of RESTFulDemo http://localhost:XXXX/ Type the Routingprefix name ―RestService ― RestService‖‖ (string value given in the global.asax the global.asax file). 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. Language
Visual C# or Visual Basic
Target Framework
.NET Framework 4
Installed Templates
WCF
Template
Console Application
Name
RESTClient
Step 2 Collapse | Copy Code
do { try { string content; string content;
Console.WriteLine( "Enter Method:"); Method:" ); string Method string Method = Console.ReadLine(); Console.ReadLine(); Console.WriteLine("Enter Console.WriteLine("Enter URI:"); URI:" ); string uri string uri = Console.ReadLine(); Console.ReadLine(); HttpWebRequest req = WebRequest.Create(uri) as HttpWebRequest; HttpWebRequest; req.KeepAlive req.KeepAlive = false false; ; req.Method = Method.ToUpper(); Method.ToUpper(); if (("POST,PUT" if (( "POST,PUT" ).Split( ',' ',').Contains(Method.ToUpper())) ).Contains(Method.ToUpper())) { Console.WriteLine( "Enter XML FilePath:" ); string FilePath string FilePath = Console.ReadLine(); content = (File.OpenText(@FilePath (File.OpenText(@FilePath)).ReadToEn )).ReadToEnd(); d(); byte[] buffer = Encoding.ASCII.GetBytes byte[] Encoding.ASCII.GetBytes(content); (content); req.ContentLength = buffer.Length; req.ContentType = "text/xml" ; Stream PostData = req.GetRequestStream(); PostData.Write(buffer, 0, buffer.Length); buffer.Length); PostData.Close(); } HttpWebResponse HttpWebResponse resp = req.GetResponse() req.GetResponse() as HttpWebResponse; HttpWebResponse; Encoding enc = System.Text.Encoding.GetEncoding( 1252 1252); ); StreamReader loResponseStream = new StreamReader(resp.GetRe StreamReader(resp.GetResponseStrea sponseStream(), m(), enc); string Response = loResponseStream.ReadTo loResponseStream.ReadToEnd(); End(); loResponseStream.Close(); resp.Close(); Console.WriteLine(Response); } catch (Exception catch (Exception ex) { Console.WriteLine(ex.Me Console.WriteLine(ex.Message.ToStri ssage.ToString()); ng()); }
Console.WriteLine(); Console.WriteLine( "Do you want to continue?" ); } while while (Console.ReadLine().ToUpper() (Console.ReadLine().ToUpper() == "Y" "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 Enter Method:
Get
Enter URI:
http://localhost:XXXX/restservice
It gives the XML output in the console screen.
HTTP POST Operation Enter Method:
Post
Enter URI:
http://localhost:XXXX/restservice
Enter XML File Path:
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. Collapse | Copy Code
[OperationContract] [WebGet(UriTemplate = "{id}" "{id}")] )] Person GetAPerson( string string id); 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.
Which is better, REST or SOAP? This is one of the most common questions I get about REST, and it is probably the least fair. Both REST and SOAP are often termed "Web services," and one is often used in place of the other, but they are totally different approaches. REST is an architectural style for building client -server applications. SOAP is a protocol specification for exchanging data between two endpoints. Comparing REST with the remote procedure call (RPC) style of building client-server applications would be more accurate. RPC is a style (rather than a pr otocol, which is what SOAP is) of building client-server applications in which a proxy (generally generated from metadata) is used in the client's address space to communicate with the server and the proxy's interface mimics the server's interface. Although SOAP doesn't require the RPC style, most modern SOAP toolkits are geared toward (at least they default to) using RPC. In contrast to RPC, REST lacks the metadata-generated proxy (see the next question for more information), which means that the client is less coupled to the service. Also, because REST relies on the semantics of HTTP, requests for data (GET requests) can be cached. RPC systems generally have no such infrastructure (and even when performing RPC using SOAP over HTTP, SOAP responses can't be cached because SOAP uses the HTTP POST verb, which is considered unsafe). SOAP intentionally eschews HTTP, specifically to allow SOAP to work over other protocols, so it's actually a little disingenuous to call SOAP-based services Web services. My perspective is that both REST and SOAP can be used to implement similar functionality, but in general SOAP should be used when a particular feature of SOAP is needed, and the advantages of REST make it generally the best option otherwise.
What about security? Isn't SOAP more secure than REST? This question touches one of my pet peeves because the answer is clearly no. It is just as easy to make a RESTful service secure as it is to make a SOAP-based service secure. In the majority of cases involving either REST or SOAP, the security system is the same: some form of HTTP-based authentication plus Secure Sockets Layer (SSL). Although technically the technology for secure conversations over HTTP is now called Transport Layer Security (TLS), SSL is still the name most commonly used. What is true is that a SOAP-based service, because of the extra protocols specified in the various WS -* specifications, does support end-to-end message security. This means that if you pass SOAP messages from endpoint to endpoint to endpoint, over the same or different protocols, the message is secure. If your application needs this particular feature, SOAP plus WS-* is definitely the way to go. REST prob ably wouldn't be an option here because of its dependence on HTTP, and inherently you'd be designing a multiprotocol application. I believe that the fact that SOAP with WS -* enables end-to-end message-level security is the source of the misconception that SOAP-based services are more secure than RES Tful services. Another area in which the WS-* folks have spent a lot of time and effort recently is federated security. The simple idea behind federated identity is to create trust between two companies, where authenticated users from one company can be trusted and considered authenticated by another company without the second company having to maintain the authentication information (username and password, typically). The various WS-* specifications have implementations from all the major vendors, and Microsoft is integrating the ideas into Active Directory through Active Directory Federation Services (ADFS). In the realm of federated security, the WS-* arena certainly has more standards than the RESTful arena (and this will probably always continue to be the case), but there are efforts to support federated security in the world of REST. OpenID is one such effort. The .NET Servic e Bus (part of Windows Azure) also contains a federated identity service, which works just as well with HTTP (and therefore REST) as it does with SOAP-based services.
What about transactions? Here is another area in which SOAP and WS -* have explicit support for an "advanced" feature and REST has none. WS-Atomic Transactions supports distributed, two-phase commit transactional semantics over SOAPbased services. REST has no support for distributed transactions. Generally speaking, if you want something like transactions in a RESTful system, you create a new resource. (Creating a new resource whenever you run into a problem with a RESTful system generally solves most problems.) You can have a resource called Transaction. When your client needs to do something transactional (such as transferring money between two bank accounts), the client creates a Transaction resource that specifies all the correct resources affected (in my example, the two bank accounts) by doing a POST to the Transaction factory URI. The client can then perform updates by sending a PUT to the transaction URI and close the transaction by sending a DELETE to the URI. This, of course, requires some amount of hand- coding and explicit control over your system, whereas the WS Atomic Transactions system is more automatic because (in the case of Windows C ommunication Foundation) it is tied to your runtime's plumbing. If your system absolutely needs atomic transactional semantics across diverse systems, WS- Atomic Transactions is probably the way to go. Using distributed transactions in this way may or may not be smart because it increases the coupling between the two systems and creates potential problems if you aren't controlling the code on both ends. But the most important thing is to use the right tool for the right job (once you've figure out what the right job is). In defense of REST, I think it is fair to say that given today's distributed, service-oriented architectures, coupling two endpoints so tightly using a distributed transaction may not be the best design. On the other hand, some situations call for this type of functionality, and if you need it, use SOAP and WS-Atomic Transactions.
What about interoperability? Isn't SOAP supposed to be about interoperability? Isn't SOAP more interoperable than REST? If you define interoperability as the technical ability to communicate between two divergent endpoints, I assert that REST wins the interoperability battle hands down. Since one of the driving points behind creating the SOAP specification was to create an interoperable way to communicate between different platforms and different languages, many people are surprised by this assertion. But a funny thing happened on the way to widespread interoperability: the WS-* specifications (and vendors' implementations of said specifications) made SOAP services less interoperable rather than more interoperable. The problem in the SOAP and WS -* arena is the large number of different standards (and versions of each of those standards) to choose from. And when a particular vendor chooses to impl ement a particular standard, that vendor often provides an implementation that is just slightly different from another vendor's (or all others). This leads to problems whenever you have to cross v endor boundaries (languages and operating system). Of course, even to use SOAP you need a SOAP toolkit on your platform, which most (but not all) platforms have today. And then you have to deal with myriad WS -* specifications and figure out which to use (or not to use) and how that affects interoperability. To be honest, it's kind of a mess out there. In terms of platforms, REST has the advantage because all you need to use REST is an HTTP stack (either on the client or the server). Since almost every platform and device has that today, I would argue that REST has the widest interoperability. Given that mobile devices, household devices, POS devices, DV D players, and TVs all have Internet connectivity, there are more and more platforms for which having a full SOAP toolkit is impossible or unlikely. And even if you do have a SOAP toolkit for a particular platform, the chance of it working with another platform's implementation is not 100%.
But what about metadata? So what if REST is so interoperable —there's no WSDL with REST, and without WSDL, I can't generate a client-side proxy to call a service. REST is hard to use. It's true that in the world of REST, there is no d irect support for generating a client from server-side-generated metadata, as there is in the world of SOAP with Web Service Description Language (WSDL). A couple of efforts are being made to get such support into REST, one being a parallel specification, known as WADL (Web Application Description Language). The other is a push to use WSDL 2.0 to describe RESTful endpoints. I often say that REST is simple, but simple doesn't always mean easy. SOAP is easy (because of WSDL), but easy doesn't always mean simple. Yes, using WSDL makes generating a proxy for a SOAP-based service easier than writing the code to call a RESTful service. But once you generate that proxy, you still have to learn the API. Nothing in t he WSDL tells you which method to call first or second or whether you need to call the methods in any particular order at all. These are all things you need to figure out after you generate the proxy and are prototyping the code to use the service. Building a client against a RESTful service means you are l earning the service and how it works as you build the client. Once you have finished, you have a complete understanding of the service, its resources, and the interaction you can have with those resources. To me, this is a big benefit. Since RESTful services follow the constraints of REST (at least they are supposed to), there is a convention that you can easily follow as you determine the different parts of the service. Also, out in the wilds of developer-land, most services are wrapped in something often called a "service agent," which is another layer of indirection to protect clients from changes in the service layer. This may be needed in either REST or SOAP. Another point is that metadata-generated proxies are part of what SOAP was meant to get away from in the RPC era, namely local-remote transparency. The concept of having an API on the client that matches the API on the server was considered to be a bad idea, but that's exactly what happens in most SOAP-based services. Having a metadata-generated proxy in REST also reduces the chances of taking advantage of hyperlinking. Using hypertext as the engine of application state (HATEOAS) is one of the constraints of REST, and using it requires a more loosely coupled client API. The last point I'll make is that as support for REST becomes more ubiquitous, building clients will get easier and easier. If you look at the Windows Communication Foundation (WCF) REST starter kit , it includes facilities that head in this direction. The new HttpClient API makes using HTTP much easier than using the .NET WebRequest/WebResponse API. Also, there is a new Paste as XML Serializable tool, which allows you to copy a piece of XML (say from the documentation of a RESTful endpoint) and generate a .NET type that can represent that XML instance in your application. This is similar to what the W CF tools do automatically for the whole service with WSDL. Over time, these tools will b ecome much more sophisticated, further simplifying the client experience in WCF when using RESTful services.
What if I want to use a transport other than HTTP? The common (somewhat sarcastic) answer from the REST community here is, "Go ahead, there isn't anything stopping you." Realistically, however, REST is currently tied to HTTP, if only because most developers and teams of developers do not have the time for the engineering effort necessary to get the semantics of REST to work over, say, TCP/IP. The common answer is technically correct, because nothing is stopping you from im plementing the concepts of REST over other protocols, but until vendors add support for this, I find it a dubious proposition for most.
After all that information, aren't you telling me that REST is good for Internet-facing applications, and SOAP for enterprise applications?
If you've read the rest of this column, you can pr obably imagine that I think this statement is generalized and false. Often I hear this sentiment after discussing the lack of explicit distributed transaction support in REST versus the explicit support in WS-Atomic Transactions. My retort is generally something like "Well, ASP.NET doesn't have support for distributed transactions, but does that m ean ASP.NET isn't useful for enterprises?" My point is that not every technology solves every pro blem, and there are plenty of technologies that don't support the typical features people think of when they think of enterprises but that are incredibly helpful f or enterprises nonetheless. In fact, when I think of enterprise applications, I often think of speed and scalability —scalability being one of the main differences between REST and SOAP. SOAP services are much harder to scale than RESTful services, which is, of course, one of the reasons that REST is often chosen as the architecture for services that are exposed via the Internet (like Facebook, MySpace, Twitter, and so on). Inside enterprises, applications also often need to scale as well. Using REST means that you can take advantage of HTTP caching and other features, like Conditional GET, that aid in scaling services. Many of these techniques can't be used with SOAP because SOAP uses POST only over HTTP.
Bottom Line I hope that after you read this column, you'll think that the answer to " Which is better, REST or SOAP?" is "It depends." Both the REST architectural style and SOAP and the WS -* protocols have advantages and disadvantages when it comes to building services. Those of us in the RESTafar ian camp (yes, I must giv e full disclosure here: I am definitely in that camp) believe that for most service situations, REST provides more benefits than SOAP or WS-*. On the other hand, SOAP and WS-* have some features that are easy (and possible) to implement using REST. When you need those specific features, you definitely want to use runtimes and toolkits that can provide those features. Although this column wasn't specifically about WCF, one nice feature of adopting WCF is that it supports both REST an d SOAP/WS-*. Moving back and forth between the two worlds becomes easier if you have one programming and runtime model to learn.
Converting SOAP-based WCF Service to RESTful Design
Introduction When SOAP is believed to be overkill, some developers may choose RESTful services. REST (Representative State Transfer) is mostly used when developers need high range of interoperability and when trying to restrict themselves to basic XML messages or JSON that are transmitted over HTTP. RESTful services are fundamentally different from SOAP-based services because they don't attempt to achieve transport neutrality. In fact, RESTful services typically embrace HTTP as the only transport used throughout the system. Using REST, developers can model their services as resources and give these resources unique identifiers in the form of URIs. In this article, we will take an existing SOAP-based service and convert it over to a more RESTful design.
Background
The Existing WCF SOAP Based Service SOAP is developed on a great deal of work that's t hat's been happening throughout the industry to implement a completely new protocol stack for services. It means that additional features or capabilities that we want to implement for our services should be possible to implement in a transport neutral way. And we'll accomplish that in this protocol stack by using an XML-based messaging layer. Now, this is where SOAP comes into the picture. SOAP is a particular XML vocabulary for packaging up messages that we need to transmit to our services. The following is the code for the WCF based service before it‘s converted to a RESTful service. The backend is using Entity Framework utilizing the Northwind database. Then it‘s followed by an image, which is the sample result of the GetAllProducts , showing the SOAP request and response. Collapse | Copy Code
using System; using System; using using System.Collections.Generic; using System.Linq; using System.Linq; using System.Text; using System.Text; using using System.Threading.Tasks; using using System.Runtime.Serialization; using using System.ServiceModel; namespace SoapToRESTfullDemo SoapToRESTfullDemo { [ServiceContract] public interface IProductService IProductService { [OperationContract] List List GetAllProducts(); GetAllProducts(); [OperationContract] ProductEntity ProductEntity GetProductByID( GetProductByID( int int productID); productID); [OperationContract] bool UpdateProduct(ProductEnt UpdateProduct(ProductEntity ity product); } [ServiceBehavior(InstanceContextMode=InstanceContextMode. Single Single)] )] public class class ProductService ProductService : IProductService IProductService { #region IProductService #region IProductService Members public List List GetAllProducts() { List products = new List(); List(); ProductEntity ProductEntity productEnt = null null; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { List prods = (from p in in NWEntities.Products select p).ToList(); p).ToList(); if (prods if (prods != null null) ) { foreach (Product foreach (Product p in in prods) prods) { productEnt = new ProductEntity() ProductEntity() { ProductID = p.ProductID, ProductName = p.ProductName, QuantityPerUnit QuantityPerUnit = p.QuantityPerUnit, p.QuantityPerUnit, UnitPrice = (decimal ( decimal)p.UnitPrice, )p.UnitPrice, UnitsInStock UnitsInStock = ( int int)p.UnitsInStock, )p.UnitsInStock,
ReorderLevel ReorderLevel = ( int int)p.ReorderLevel, )p.ReorderLevel, UnitsOnOrder UnitsOnOrder = ( int int)p.UnitsOnOrder, )p.UnitsOnOrder, Discontinued Discontinued = p.Discontinued p.Discontinued }; products.Add(productEnt); } } } return products; return products; } public ProductEntity public ProductEntity GetProductByID( int int productID) productID) { ProductEntity productEnt = null null; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { Product prod = (from p in NWEntities.Products NWEntities.Products where p.ProductID == productID select p).FirstOrDefault(); p).FirstOrDefault(); if (prod if (prod != null null) ) productEnt = new ProductEntity() ProductEntity() { ProductID = prod.ProductID, ProductName = prod.ProductName, QuantityPerUnit QuantityPerUnit = prod.QuantityPerUnit, prod.QuantityPerUnit, UnitPrice = (decimal ( decimal)prod.UnitPrice, )prod.UnitPrice, UnitsInStock UnitsInStock = ( int int)prod.UnitsInStock, )prod.UnitsInStock, ReorderLevel ReorderLevel = ( int int)prod.ReorderLevel, )prod.ReorderLevel, UnitsOnOrder UnitsOnOrder = ( int int)prod.UnitsOnOrder, )prod.UnitsOnOrder, Discontinued Discontinued = prod.Discontinued prod.Discontinued }; } return productEnt; return productEnt; } public bool bool UpdateProduct(ProductEntity product) { bool updated bool updated = true true; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { var productID var productID = product.ProductID; Product productInDB = (from p in in NWEntities.Products where p.ProductID == productID select p).FirstOrDefault(); p).FirstOrDefault(); if (productInDB if (productInDB == null null) ) { throw new new Exception( Exception("No "No product with ID " + product.ProductID); product.ProductID); } NWEntities.Products.Rem NWEntities.Products.Remove(productI ove(productInDB); nDB); productInDB.ProductName productInDB.ProductName = product.ProductName; product.ProductName; productInDB.QuantityPer productInDB.QuantityPerUnit Unit = product.QuantityPerUnit; product.QuantityPerUnit; productInDB.UnitPrice productInDB.UnitPrice = product.UnitPrice; product.UnitPrice; productInDB.Discontinue productInDB.Discontinued d = product.Discontinued; product.Discontinued; NWEntities.Products.Att NWEntities.Products.Attach(productI ach(productInDB); nDB); NWEntities.Entry(productInDB).State = System.Data.EntityState.Modified; int num int num = NWEntities.SaveChanges(); NWEntities.SaveChanges(); if (num if (num != 1) { updated = false false; ; } } return updated; return updated;
} #endregion } }
Using the Code The Conversion The interaction of REST is done through a standard uniform interface or service contract. In this case, it would be the methods defined by the HTTP protocol specifically GET, POST, PUT, and DELETE. By standardizing on the uniform interface, developers can build infrastructure around the semantic meaning of each operation and make performance and scalability improvements when possible. For security, RE ST simply uses HTTPS; it just leverages SSL for all its security needs. We will start with the three operations: GetAllProducts, which returns all products, GetProductByID where we provide a productID for the product that we are looking for, and finally, UpdateProduct will demonstrate the WebInvoke operation which is passing the PUT method.
First, we need to add the ServiceModel.Web assembly which gives us access to the WebGet and WebInvoke methods. The following is the step by step instruction for converting the IProduct interface: 1. 2. 3.
In the Product interface, let‘s define our URI mapping which specifies what URI to map to; for [WebGet(UriTemplate mplate = "products") "products")] ] for the GetAllProducts method instance,[WebGet(UriTe For the GetProductByID, we will need to pass in the base address, followed by the product, then followed by the productID - [WebGet(UriTemplate = "product/{productID}")] WebInvoke uses the same property. The update/submit method uses the POST method; for [WebInvoke(Method thod = "POST", UriTemplate = "product")] instance,[WebInvoke(Me
Your complete code should look like the following (as you can see, the difference with SOAP-based is just around the interface): Collapse | Copy Code
using System; using System; using using System.Collections.Generic; using System.Linq; using System.Linq; using System.Text; using System.Text; using using System.Threading.Tasks; using using System.Runtime.Serialization; using using System.ServiceModel; using using System.ServiceModel.Web; using using System.ServiceModel.Syndication; namespace SoapToRESTfullDemo SoapToRESTfullDemo { [ServiceContract] public interface IProductService IProductService { [WebGet(UriTemplate = "products" )] [OperationContract] List List GetAllProducts(); GetAllProducts(); //UriTemplate //UriTemplat e - the base base address, followed followed by product product and followed by the ID
[WebGet(UriTemplate = "product/{productID}" "product/{productID}")] )] [OperationContract] ProductEntity ProductEntity GetProductByID( GetProductByID( string string productID); productID); //WebInvoke has the same same property - for update/submit update/submit use POST. POST. Post it to product product
[WebInvoke(Method [WebInvoke(Method = "POST" "POST", , UriTemplate = "product" "product")] )] [OperationContract] bool UpdateProduct(ProductEnt UpdateProduct(ProductEntity ity product); } [ServiceBehavior(InstanceContextMode=InstanceContextMode. Single Single)] )] public class class ProductService ProductService : IProductService IProductService { #region IProductService #region IProductService Members public List List GetAllProducts() { List products = new List(); List(); ProductEntity ProductEntity productEnt = null null; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { List prods = (from p in in NWEntities.Products
select p).ToList(); p).ToList(); if (prods != null if (prods null) ) { foreach (Product foreach (Product p in in prods) prods) { productEnt = new ProductEntity() ProductEntity() { ProductID = p.ProductID, ProductName = p.ProductName, QuantityPerUnit QuantityPerUnit = p.QuantityPerUnit, p.QuantityPerUnit, UnitPrice = (decimal ( decimal)p.UnitPrice, )p.UnitPrice, UnitsInStock UnitsInStock = ( int int)p.UnitsInStock, )p.UnitsInStock, ReorderLevel ReorderLevel = ( int int)p.ReorderLevel, )p.ReorderLevel, UnitsOnOrder UnitsOnOrder = ( int int)p.UnitsOnOrder, )p.UnitsOnOrder, Discontinued Discontinued = p.Discontinued p.Discontinued }; products.Add(productEnt); } } } return products; return products; } public ProductEntity public ProductEntity GetProductByID( string string productID) productID) { int pID int pID = Convert.ToInt32(productID); Convert.ToInt32(productID); ProductEntity ProductEntity productEnt = null null; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { Product prod = (from p in NWEntities.Products NWEntities.Products where p.ProductID == pID select p).FirstOrDefault(); p).FirstOrDefault(); if (prod if (prod != null null) ) productEnt = new ProductEntity() ProductEntity() { ProductID = prod.ProductID, ProductName = prod.ProductName, QuantityPerUnit = prod.QuantityPerUnit, UnitPrice = (decimal ( decimal)prod.UnitPrice, )prod.UnitPrice, UnitsInStock = ( int int)prod.UnitsInStock, )prod.UnitsInStock, ReorderLevel = ( int int)prod.ReorderLevel, )prod.ReorderLevel, UnitsOnOrder = ( int int)prod.UnitsOnOrder, )prod.UnitsOnOrder, Discontinued Discontinued = prod.Discontinued prod.Discontinued }; } return productEnt; return productEnt; } public bool bool UpdateProduct(ProductEntity product) { bool updated bool updated = true true; ; using ( using (var var NWEntities NWEntities = new NorthwindEntities()) NorthwindEntities()) { var productID var productID = product.ProductID; Product productInDB = (from p in in NWEntities.Products where p.ProductID == productID select p).FirstOrDefault(); p).FirstOrDefault(); if (productInDB if (productInDB == null null) ) { throw new new Exception( Exception("No "No product with ID " + product.ProductID); product.ProductID); } NWEntities.Products.Rem NWEntities.Products.Remove(productI ove(productInDB); nDB);
productInDB.ProductName productInDB.ProductName = product.ProductName; product.ProductName; productInDB.QuantityPer productInDB.QuantityPerUnit Unit = product.QuantityPerUnit product.QuantityPerUnit; ; productInDB.UnitPrice productInDB.UnitPrice = product.UnitPrice; product.UnitPrice; productInDB.Discontinue productInDB.Discontinued d = product.Discontinued; product.Discontinued; NWEntities.Products.Att NWEntities.Products.Attach(productI ach(productInDB); nDB); NWEntities.Entry(productInDB).State = System.Data.EntityState.Modified; int num int num = NWEntities.SaveChanges(); NWEntities.SaveChanges(); if (num if (num != 1) { updated = false false; ; } } return updated; return updated; } #endregion } }
Once we have the interface modified, we can then modify the configuration file ( app.config) to wire up the service. The following are the steps for modifying the app.config: 1.
Change binding from basic to WebHttpBinding -
binding="wsHttpBinding" binding="wsH ttpBinding" contract="S contract="SoapToRESTful oapToRESTfullDemo.IProdu lDemo.IProductService"> ctService"> name="SoapToRESTfullDemo oRESTfullDemo.Service1Beh .Service1Behavior"> avior"> 2. Add a new behavior - 1Behavior"> Your app.config should look like the following: Collapse | Copy Code
> > > > >
automatically.
--> > ="localhost"/> > >
="IMetadataExchange"/> > > or">
> > > > > >
Running the REST Service
We basically expose the same functionality as we did using SOAP, but these functionalities are exposed through the standard HTTP uniform service contract. The URI will determine which functionality is being invoked. Let‘s start by running the host. As seen in the following image, the host displays the base address, which is specified in the configuration file ( http://localhost:8080/productservice).
Now, we can see the service invocation by typing in the full address in the Web browser; such ashttp://localhost:8080/productservice/products. This address will display the following result for the GetAllProducts(remember the UriTemplate is calling for ―products‖):
When calling GetProductByID, we will need to pass in the product ID as part of the query string; for instance,http://localhost:8080/product/productID. The following is the result, which returns only a product with an ID of 1:
MISC-- Difference Between SOAP and REST Difference between REST and SOAP
Definitions
REST RESTs sweet spot is when you are exposing a public API over the internet to handle CRUD operations on data. REST is focused on accessing named resources through a single consistent interface.
SOAP SOAP brings it’s own protocol and focuses on exposing pieces of application logic (not data) as services. SOAP exposes operations. SOAP is focused on accessing named operations, each implement some business logic through different interfaces. Though SOAP is commonly referred to as “ as “web web services” services” this this is a misnomer. SOAP has very little if anything to do with the Web. REST provides true “Web services” based on URIs and HTTP. By way of illustration here are few calls and their appropriate home with commentary.
getUser(User);
This is a rest operation as you are accessing a resource (data).
switchCategory(User, switchCategory( User, OldCategory, Ol dCategory, NewCategory)
This is a SOAP operation as you are performing an operation. Yes, either could be done in e ither SOAP or REST. The purpose is to illustrate the conceptual difference.
Why REST? Here are a few reasons why REST is almost always the right answer. Since REST uses standard HTTP it is much simpler in just about ever way. Creating clients, deve loping APIs, the documentation is much easier to understand and there aren’t very many things that REST doesn’t do easier/better than SOAP. REST permits many different data formats where as SOAP only permits X ML. While this may seem like it adds complexity to REST because you need to handle multiple formats, in my experience it has actually
been quite beneficial. JSON usually is a better fit for data and parses much faster. REST allows better support for browser clients due to it’s support for JSON. REST has better performance and scalability. REST reads can be cached, SOAP based reads cannot be cached. It’s a bad argument (by authority), but it’s worth mentioning that Yahoo uses REST for all their services including Flickr and del.ici.ous. Amazon and Ebay Eb ay provide both though Amazon’s internal usage is nearly all REST source source.. Google used to provide only SOA P for all their services, but in 2006 they deprecated in favor of REST source source.. It’s interesting how there has been an internal battle between rest vs soap at amazon. For the most part REST dominates their architecture for web services.
Why SOAP? Here are a few reasons you may want to use SOAP.
WS-Security While SOAP supports SSL (just like REST) it also supports WS-Security which adds some enterprise security features. Supports identity through intermediaries, not just point to point (SSL). It also provides a standard implementation impl ementation of data integrity and data privacy. Calling it “Enterprise” isn’t to say it’s more secure, it simply supports some security tools that typical internet services have no need for, in fact they are really only needed in a few “enterprise” scenarios. scenario s.
WS-AtomicTransaction Need ACID Transactions over a service, you’re going to need SOAP. While REST supports transactions, it isn’t as comprehensive and isn’t ACID compliant. Fortunately ACID transactions almost never make sense over the internet. REST is limited by HTTP itself which can’t provide two-phase two -phase commit across distributed transactional resources, but SOAP can. Internet apps generally don’t need this level of transactional reliability, enterprise apps sometimes do.
WS-ReliableMessaging Rest doesn’t doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying. SOAP has successful/retry logic built in and provides end-to-end reliability even through SOAP intermediaries.
Summary In Summary, SOAP is clearly useful, and important. For instance, if I was writing an iPhone application to interface with my bank I would definitely need to use SOAP. All three features above are required for banking transactions. For example, if I was transferring money from one account to the other, I would need to be certain that it completed. Retrying it could be catastrophic if it succeed the first time, but the response failed.
The bigger picture Technologies are changing, for good or for bad, and we can’t do anything about it except it except to embrace them and adapt. In my experience, I’ve found that the topic of web services is quite o btrusive to many developers, mainly due to the fact there are at least a dozen of technologies (by Microsoft alone), a lot of buzzwords and strange acronyms that seem interchangeable at first glance. It’s overwhelming. In this part of the article, I’ll try to touch some basic, but important, pieces of information related to web services, which will give you the basic theoretical knowledge to understand the different between the services, new Asp.Net Web API , the Asp.Net the Asp.Net MVC end end points and the different services WCF prov ides.
The need for standards One of the most common issues involved in web communications is the mismatch in the format of the data sent. Every proprietary system is free to use whatever rules it wishes when composing a message between its modules. With the advance of the internet, however, it became clear that the cost of the synchronization between the different applications/platforms is too high to af ford, and software community began to look for a standardized solutions to address the problem. One of these solutions is SOAP .
What is SOAP ? The Simple Object Access Protocol (SOAP) is an attempt to define a standard for creating web service APIs. It is a pattern, a web service architecture, which specifies the basic rules to be considered service APIs. while designing web service platforms. It typically uses HTTP as a layer 7 protocol, although this is not mandatory. The SOAP message itself consists of an envelope, inside of which are the SOAP headers and body, the actual information we want to send. It is based on the standard XML format, designed especially to transport and store structured data. SOAP may also refer to the format of the XML that the envelope uses. SOAP is a mature standard and is heavily used in many systems, but it does not use many of the functionality build in HTTP. While some consider it slow, it provides a heavy set of functionality which is a necessity in many cases. It might not be the best solution for browser-based clients, due to its custom format.
What is REST ? The Representational State Transfer (REST) is another architectural pattern (resource-oriented), analternative an alternative to SOAP . Unlike SOAP, RESTful applications use the HTTP build-in headers (with a variety of media-types) to carry meta information and use the GET, POST, PUT and DELETE verbs to perform CRUD operations. REST is resource-oriented and uses clean URLs (or RESTful URLs). For example : http://www.developingthefuture.com/index.php?page=foo becomes http://www.developingthefuture.com/foo Note: Having query parameters doesn’t exclude REST, the query parameters can actually complement the restful URL by making it more versatile (thanks Ugarit Ebla for pointing that in the comments ;] ) This kind of URLs syntax greatly improves both visibility and usability. It doesn’t use any query strings, and it also provides certain SEO benefits (the crawlers just love plain text). The body of the REST message can be XML, JSON or any other format, although JSON is usually the preferred choice. On the other hand, you can’t use JSON with SOAP. Or at least not e ntirely, because SOAP uses XML by definition for it’s envelope. I t should also mentioned that REST is, by design, protocol-agnostic, although it is usually used with HTTP. Read more: more: What’s the difference between JSON and XML ?
Atom and AtomPub The name Atom relates to two similar terms : Atom Syndication Format and Format and Atom Atom Publishing Format The Atom The Atom Syndication Format is is a XML-based XML- based format used for web feeds (or news feeds). It’s basically an alternative to RSS. The Atom Publishing Protocol (AtomPub) is (AtomPub) is a simple HTTP-based protocol used for the management (creation, deletion, update) of web resources – the feeds at first exactly.
And what is OData ? Remember that part about the need for standardization ? The Open Data Protocol Protoco l (or simply OData OData)) is a protocol based on AtomPub and REST. It has most of the REST specifics and more than AtomPub’s specification have defined. It’s designed to define the the standard standard way of communication to a web service. Like S QL for relational data, you don’t care what RDBMS is down there – you simply use SQL to query data. And that’s the idea. Don’t forget we are talking about specifications here, protocols, not implementa implementations. tions. Whether or not a given framework or library will implement a given functionality is up to the development team. It is also worth mentioning that OData was released by Microsoft, although it is truly open source (just like version 4 of Asp.Net MVC, by the way). I t will probably be the protocol of choice for any future service-oriented technologies developed by Microsoft.
What improvements does OData provide over AtomPub ? AtomPub provides a way of getting, updating and deleting records from a model. It does not provide, however, a data model that defines typed or untyped values on an entity. It also doesn’t provide any kind of a build-in query language to filter the entities we need. More on that later.
Summary
SOAP - A service architecture - XML based -
Runs on HTTP but envelopes the message Slower than REST Very mature, a lot of functionality Not suitable for browser-based clients
REST - A service architecture (resource-oriented) - Uses the HTTP headers to hold meta information (although it is protocol-agnostic) - Can be used with XML, JSON or whatever necessary - Usually used with JSON due to the easily parsable content - Faster than SOAP - It uses semantic media types OData - A protocol - Based on HTTP, AtomPub and JSON - RESTful by design - Microsoft implementation, yet truly open source - Used in the latest Microsoft service-oriented technologies (more on that later)
My idea of writing this article was to introduce you to the new Asp.Net Web API, compared to the various services in WCF (SOAP services, WebHttpServices, Data services, etc.) and to the Asp.Net MVC alternative. I decided, however, to first give you this quick introduction so you can know what’s behind the new Microsoft service-oriented technologies (although these terms are platform-agnostic) and why it w as used. In my next article on the subject, I’ll focus on the practical part and the actual technologies/frameworks that use these protocols and patterns. If you want to read more o n the topic, you can check the following document document written written by Vivin Suresh Paliath,, which forms a nice introduction into the differences between SOA, ROA, SOAP and REST in general. Paliath
End MISC.
RESTful Web Services: A Quick-Start How-to Guide - Part 1 Among PowerBuilder 12.5 .NET's new features comes the ability to use WCF to call RESTful web services. This article, the first in a two-part series, provides a PowerBuilder 12.5 .NET developer with the
foundational knowledge and skills to rapidly get up an d running building PowerBuilder RESTful Web Service clients. Along the way I'll share with you a few tips and workarounds.
Introduction PowerBuilder 12.0 .NET provided the ability to call SOAP-based web services using Microsoft's .NET 3.5 WCF API. I encourage those of you not familiar with WCF and SOAP to view my PowerBuilder WCF primer and StockTrader reference application overview hosted on Sybase.com. You can get to all my free tutorials t utorials fromhttp://yakovwerde.ulitzer.com/node/1551687 from http://yakovwerde.ulitzer.com/node/1551687.. New with version 12.5, along with an upgrade to WCF 4.0, is the ability to call RESTful web services, an increasingly popular mechanism for accessing remote resources in SOA applications. In this article I'll help you gain some foundational understanding and definitions, then familiarize you with the mechanics of coding a client to retrieve data from a responseoriented RESTful service. In Part 2, I'll explore the three types of request-oriented operations.
What Are RESTful Web Services? In a nutshell, RESTful services are "web natural" and lightweight. They leverage HTPP's native GET, PUT, POST & DELETE methods to invoke service methods at well -known URIs. Much has already been written and is freely available on the Internet about the nature and implementation of RESTful web services and how they compare to SOAP/WSDL services. s ervices. Instead of rehashing what has already been thoroughly described, Listing 1 provides a couple of web references from which you can glean an understanding of the technology. If you need more information, a quick search on your favorite s earch engine will turn up more references. If you're really serious and would like a full-sized book, you can purchase Jon Flanders' RESTful .NET published published by O'Reilly. 1. 2.
A Guide to Designing and Building RESTful Web Services with WCF 3.5 Learn REST: A Tutorial Listing 1: Useful Web References
One pragmatic difference between WSDL / SOAP services and RES Tful services from the client v iewpoint is the amount of onus placed on the client developer. SOAP services are fully described in a WSDL document, including their service methods, input parameters and return types. A PowerBuilder developer has no responsibility other than to input the WSDL location into the wizard or project painter and click the generate proxy button. The project painter does the rest. SOAP calls are also method me thod based. At runtime the developer instantiates a single proxy and invokes specific methods as necessary. With RESTful services, however, the developer has more responsibility in defining the interface. He has to get hold of either a schema (XSD) document or .NET assembly that fully describes the types in the returned XML or JSON, OR a sample result set with sufficiently varied data to help the proxy generator decipher the return structure. He also has to know enough about the structure of the return type so as to be able to review the wizard's work and make corrections as necessary (more about this later). Calls to a RESTful service are not method based - simply navigating to the service URI with correct parameters appended gets you a response. This means there is one proxy per service (method), hence more code objects to maintain.
What Is JSON? Depending on how they are implemented, RESTful web services can r eturn data in one of several standard formats. Among the possible formats are XML, CSV, RSS, ATOM and JSON. PowerBuilder 12.5 allows you
to choose either XML or JSON for your transfer format. What is J SON? The upshot is that JSON is a JavaScript / AJAX browser friendly data transfer format. B ecause AJAX is a pervasive web t echnology, many services are only available in JSON flavor. Listing 2 provides some useful references from which you can get more background on JSON. JSON presents no problem for PowerBuilder! At design time you can provide a sample data set in JSON or XML format to the project painter. The project painter will parse the sample data, JSON data and generate the .NET reference objects you'll need to work with your data. At runtime JSON-based data transfer is parsed and converted to .NET value objects. The good news is that as a PB progra mmer you will not have to write JSON; however, you will have to read it to understand how a result set is constructed. 1. 2.
Quick overview of this JSON JSON, a formal definition Listing 2: Useful JSON References
Viewing JSON IE 9 does not have a native facility for viewing JSON data. You'll need to use a tool to view the output data. One such tool is http://www.jsonviewer.com/ . Once on the page, input the full invocation URL and click the ‗Get JSON and Parse' button. Figure 1 shows what you might see.
Figure 1: JSON Viewer
If you are using Fiddler to monitor HTTP traffic (http://www.fiddler2.com/fiddler2 http://www.fiddler2.com/fiddler2)), install the JSON viewer viewer..Figure 2 shows how you can view returned JSON objects in Fiddler.
Figure 2: Fiddler with JSON Viewer
Getting Started with PowerBuilder RESTful clients Sidebar Tip PowerBuilder relies on tools from the .NET 4.0 SDK to generate many of the code artifacts your client application will need. At the time of this writing 12.5 is in beta release version. The installer does not install the .NET 4.0 SDK. You will need to download and install the .NET 4.0 SDK from Microsoft. If the SDK is not installed on your system, you will get an error message when you attempt to generate a proxy. For this tutorial I'm going to the use the free GeoNames service located at www.GeoNames.org www.GeoNames.org.. The GeoNames geographical database covers many countries and contains over eight million place names that are available for download free of charge. GeoNames provides a robust set of RESTful services via which you can access their database. Figure 3 shows a partial listing of available services. You can find the full list of available services at a thttp://www.geonames.org/export/ws-overview.html http://www.geonames.org/export/ws-overview.html.. To explore GeoNames on your own, you'll want to create a free user account using the Login link on the upper right side of their home page. Having an account is important since you'll need to provide your username as a parameter to your service calls and access using the "demo" user name is extremely limited.
Figure 3: Some GeoName Services
Getting Started Here's a list of the information you'll need to have handy before entering inputs in the RESTful service project wizard: 1. 2. 3. 4. 5.
The name of PBL into which you want to s ave your project object (usually the same pbl containing the project object you use to generate you EXE). The name of PBL into which the project painter will generate the code for your proxy class (you may want a separate pbl just for proxies that you can batch refresh if need be). The web method type GET, POST, PUT or DELETE. A name for your proxy class. You will interact with this class in your code. I'd suggest using the P_ prefix as part of your name. A name for the NameSpace you want to put your proxy class in - you can leave it blank to use the default namespace.
6. 7. 8.
9. o o o
The URI for the service s ervice including any parameters needed for the call. The service's return data format: XML or JSON. A name for a generated assembly. This assembly will contain value objects used as parameter parameterss and/or return types. It will be added by the wizard to your target as a reference. This name will also become the namespace for the assembly. A source to help the painter determine the return data type. There are three options, choose one: A schema document (XSD) that defines the structure of the returned dataset. A preexisting assembly that formally defines the return type structure A sample XML snippet or JSON object whose data is rich and robust enough that the tool can figure out the data types from its contents.
Sidebar Tip As shown in Figure 4 you can cause the generator to include input parameters on the GetMessage( ) method by changing Service URL literal values to tokens. Identifiers inside { } will become parameter names. If you leave the literal values in, the generator will emit a parameter-less method call.
Stepping though the Wizard Creating a new proxy class is a two-step process. First, you run the w izard in order to generate the development time project object and reference assembly. Then you verify your inputs in the project painter and deploy the project object to generate your runtime code artifacts. Let me visually guide you through the process. For this example I'm going to do a GET on the GeoName findNearbyWikipedia service. Follow Figures 5 through 12 in sequence to overview the complete process.
Figure 5: Wizard - Step 1
Figure 6: Wizard - Step 2
Figure 7: Wizard - Step 3
Figure 8: Wizard - Step 4
Figure 9: Wizard - Step 5
Figure 10: Project Painter with generated project object
Figure 11: Click the Generate Button on the Painter Toolbar
Figure 12: Generated Code Code objects
Sidebar Tip The invocation method for a GET will always be named GetMessage( ) . It is a good practice to include the service name as part of its corresponding proxy class name. This will make its intent clear.
Sidebar Tip
If you use a sample dataset (XML or JSON) to generate your reference reference assembly, it's important that you examine the emitted assembly to verify the data type o f each property. Occasionally the Microsoft parser will misinterpret a property's type. You'll want to correct that before moving on. There is no intermediate source code for the reference assembly, so your only recourse is to supply values to the project object that will cause it to render the property correctly. For example, a supplied postalCode element with the value ‗07960' was generated as a UInt16 instead of the expected String type. Supplying the value ‗x7960' forced the type to be rendered r endered as a String.
Generated Artifacts Let's take a more in-depth look at the generated code artifacts. Figure 13 shows the three kinds of objects o bjects generated from a project object.
Figure 13: Generated code artifacts
Project Object is a place to input your choices and a front end onto Microsoft and PowerBuilder code generation tools. You click the Generate Proxy button on the Project Object's PainterBar to kick off the code generation process Proxy Class is the class you instantiate in your code and use to call the service. Don't modify the generated code. Any changes you make to this code object will be lost when you regenerate your proxy.
To extend or modify this code, inherit from this class and write your changes in the descendant. You instantiate a proxy type object and call GetMessage( ) passing appropriate parameters to invoke the service. Figure 14, shows the contents of a typical Proxy class fronting a call to a GET method.
Figure 14: Contents of a GET proxy object
Request and Response Assemblies contain value objects returned by a GET call or passed as parameters to DELETE, POST and PUT calls. The WCF infrastructure handles converting JSON & XML into value objects and vice versa. You are spared from dealing with low-level conversion issues. Usually there will be a wrapper object that may or may not have data properties. It's the equivalent of the root element in an XML document. The wrapper object will have an array of value objects. These are the repeating roworiented XML structures. The value object will have some set of return specific data values. Figure 15 shows the contents of a typical Response Assembly.
Figure 15: Contents of a typical Response Assembly
Scripting the Call The runtime code algorithm follows these steps: 1. 2. 3. 4.
Instantiate the proxy in the appropriate scope. Declare return value reference variables. Call the GetMessage( ) method passing applicable parameters and capture the return. Destroy the proxy or let it go out of scope. Figure 16 shows the complete code for a GET service invocation. Of course in a "real -world" application you will do something more significant with the return values than display them in a messagebox.
Figure 16: Complete code for a GET service invocation
Note that even in well-designed w ell-designed applications, things can go wrong that are outsi de the client developer's control. For example, at runtime a service can be down or totally unavailable at the known URI. Therefor even though exception handling is optional, it's a best practice to avoid runtime system errors by scripting service calls inside TRY CATCH blocks that include a robust handler for problematic conditions.
Sidebar Tip Using a single line DataWindow expression to directly load a data buffer from fro m a PowerScipt NVO array works great. However, directly assigning a .NET value object array to a DataWindow buffer using an expression throws a runtime error. As a result you have to take a more time and labor code intensive approach. You must either (a) iterate the . NET object array and call SetItem( ) for each value OR (b) assign the .NET value array to an equivalent intermediate PowerScript NVO type array and then assign it to a DataWindow.
Sidebar Tip Unfortunately, Web Service DataWindow Objects are only SOAP compatible. They have not yet become RESTful aware. To use a DataWindow for data display, you'll need to declare an external data source DataWindow and manually populate its buffer from the RESTful WS call return.
Conclusion RESTful services are becoming pervasive on the Web. The APIs of many popular services, such as Google are Yahoo, are available as RESTful services. PowerBuilder 12.5 .NET programmers now have the ability to integrate calls to RESTful services in their applications using standard tools and technologies. Long Live PowerBuilder!
RESTful Web Services: A Quick-Start How-to Guide - Part 2 Part 2 of "RESTful "RE STful Web Services: A Quick-Start How-To Guide" explores foundational issues in coding RESTful operations, including Basic Authentication and Exception handling. Along the way I'll share with you multiple real-world coding tips and workarounds.
Introduction As a teenager, one of my favorite TV shows was "The Wild Wild West." The show's description goes like this, "... a 60 minute western action series on CBS that was like no other. Special Agents James West and Artemus Gordon were spies for President Ulysses S. Grant shortly after the civil war. In every other way, they could be easily confused with James Bond of the 20th century. They had a "high-tech" (for its day) railroad car stocked with a compliment of advanced weapons. James West especially seemed to woo every beautiful woman he encountered. The agents' typical mission involved savin g the United States from some disaster or from being taken over by some evil genius." Just in case you're curious or are a fan like me, here's a link to the first part of a full episode on YouTube. What do RESTful services have to do with th e Wild Wild West? In my mind, lots. First, there's the "wildness" part. As even a brief comparison between service provider APIs will show you, all RESTful services are not created equal. Each s ervice provider, while loosely conforming to the state representation paradigm, creates requests and responses in formats that suit t heir individual styles and predilections. The onus for implementing the client side of the service falls on the developer. Then there's the inventive side of things. Just like special agent Artemus Gordon, a RESTful client developer needs gadgets, inventiveness, and a continual awareness that she's dealing with an informal (enemy) specification. Plus, on th e PowerBuilder side, there's no direct support for integrating with DataWindow technology (yet), so you'll have to invent ways to get data into and out of a display. There's also a need to protect your app against outside issues by wrapping calls in appropriate try catch blocks to handle possible HTTP exceptions in order to keep your app responsive and stable. In my opinion, without a formal schema and metadata description support, configuring RESTful state service clients will remain an art. I have to admit that I stumbled many times during experiments while writing this article. I tried calling s ervices whose communication format didn't quite match the generally expected format. One service provider expected parameters to be passed and results returned in line separated text values in the message body instead of formatting data as XML or JSON. After quite a bit of poking and debugging it became apparent PowerBuilder will only generate and interpret message body content formatted as JSON and XML. There is no way to translate from any other format. All the low -level details are handled internally and there is no way to get inside the message to change the format. Another service provider showed their API in t erms of JSON data sets, s ets, but after hours of experimentation and a little help from engineering, we discovered that the service needed multipart/form-data with the JSON sent as a form parameter. This is not a supported format. So e caveat emptor, make sure the service provider has a ‗traditional' form of RESTful API. Luckily, I believe most of the ‗big b oys' with widely used APIs do.
Oh, Those Project Objects! Before getting into details, a few words about RESTful project objects and generated code. RESTful project objects are designed to be like single shot Derringer pistols; fire one shot, then you have to reload. Each project object is capable of generating one proxy object for one method, period. That means if you are interacting with multiple web methods (GET, POST, PUT and DELETE) you're going to have multiple proxy objects. In addition, each operation, depending on its type, c an have up to two referenced .NET value objects, one for the request and one for the response. One nice thing I noticed is that if multiple services rely on the same parameter sets, you can reuse referenced value objects instead of generating superfluous carbon copies. Figure 1 shows how you'd configure the project painter to reference an already-generated already-gene rated assembly. Each reference object is placed in its own assembly inside an identically named namespace. Unfortunately it seems like you can't have multiple value objects in a single assembly or namespace. Figure 2 shows how reference object assemblies appear in the Solution Explorer. Figure 3 shows you the wizard view when choosing an existing value object assembly.
Figure 1: Reusing an already referenced assembly
Figure 2: Referenced object in Solution Explorer
Figure 3: Wizard View: Choosing and existing assembly
Here are a series of tips that I discovered while building my application: Tip 1: The project object owns its generated proxy object. That means that any modifications you make to it will be lost if you regenerate the proxy. Because I needed to make modifications to the generated code, I adapted the strategy of using project o bject generation as a starting point only. Once the proxy objects were generated to my liking, I deleted the project object to avoid accidentally nuking my code. Tip 2: If you have several services that use an identical request object or return the same result structure, you can reuse your value object definitions. Generate once, use many. Just pick them on the wizard or in the project object. Tip 3: The only door into a new project object is in via the Wizard. This is unlike Classic where there were two doorways into a new project (Wizard or empty project painter page). Tip 4: Here are a couple of neat XML sample data parsing features: First, if an XML element in the sample dataset has attributes, the attribute values are returned as part of the generated value object. Figure 4
shows a sample response dataset containing attributes; Figure 5 show the corresponding generated value object. Second, as you can see from Figure 6 that nested XML structures becomes separate objects within the generated assembly.
Figure 4: Sample DataSet with Atributes
Figure 5: Value object generated from sample dataset
Figure 6: Nested XML object
With these project object details behind us w e can now move on to two important runtime housekeeping needs: return status checking and exception handling.
Checking Return Status Some services indicate their outcome by returning data in a specific and constant format. Other services indicate their outcome by returning an HTTP status co de instead of an XML or JSON embedded status message. Still other services return status conditions wrapped in specially formatted XML or JSON structures. If you need to check a HTTP return status code outcome you'll need to get the status code from the Response object. Here's how: The response object is returned to the proxy in the form of a PBWebHttp.WebMessage object. This object has a StatusCode property of t ype MessageStatus that holds the response outcome. You can test StatusCode against enumerated values of the WebResponseStatusCode class and branch accordingly. Figure 7 shows a partial list of MessageStatus codes and their corresponding meaning. For a complete listing of HTTP 1.1 code see http://www.w3.org/Protocols/HTTP/HTRESP.html http://www.w3.org/Protocols/HTTP/HTRESP.html.. Listing 1 shows an example of testing a proxy method call status code. Collapse | Copy Code
PBWebHttp.WebMessage PBWebHttp.WebMessage msg //generate //generated d code PBWebHttp.MessageStatus l_msg_status //my custom addition Try msg = m_service.GetMessage( m_service.GetMessage() ) //an exception exception was not not thrown - check check the status status of the outcome
l_msg_status= msg.Status
if if l_msg_status.StatusCode = PBWebHttp.WebResponseStatusCode.OK! then MessageBox('Success! MessageBox('Success! ', ' ,'call returned OK' ) end if ..... Listing 1: Testing Result Staus Code
Figure 7: MessageStatus codes
Exception Handling Wizard-generated proxy code does not contain any exception handling logic. Any exceptions that occur Wizard-generated are thrown up to the caller for processing. Unhandled, these exceptions become system errors. In the web world, Response status codes in the 400 range indicate client errors; those in the 500 range signal server s erver errors. In WCF 400 and 500 codes raise exceptions. Best coding practices mandate robust exception handling. Depending on the level of detail you need to report on, you can handle exceptions either at the proxy method caller level or within the proxy method call itself. RESTful service methods, predicated predicated on HTTP, usually throw a System.Net.WebException. System.Net.WebException. Although the common System.Exception ancestor property Message contains a description of what went wrong, it's more useful to directly test the value of the returned status code. Luckily the WebException contains contains a reference to the returned returned Response object which holds the status code. Listing 2 shows an example of testing the status code when a call fails. Collapse | Copy Code
catch (System.Net.WebExcept (System.Net.WebException ion webex) System.Net.HttpWebResponse l_resp //Get the response response object object l_resp = webex.Response
if l_resp.StatusCode if l_resp.StatusCode = System.Net.HttpStatusCode.Unauthorized! then
//check its status
code
MessageBox('Your MessageBox('Your Credentials Are Invalid' , 'Uid=' 'Uid=' + + uid + '~r~nPwd=' + pwd ) return Result return Result end if Listing 2: Testing the status code
Now that you are aware of housekeeping issues, let's take a look at security concerns.
Basic Authentication WCF supports various forms of o f authentication ranging from None up to Digital Certificates. When using Basic Authentication you place your credentials in the user ID and password in request r equest header fields. If HTTP is used, the credentials are encrypted within in a plain text header (however, freely available programs such as Fidder can decrypt SSL). If HTTPS is used, then SSL encryption is applied to all transferred packets. The client/server negotiation algorithm is: (1) Client makes a r equest; (2) Server responds with a 401 unauthorized response; (3) Client responds with a request including a login header containing a user id and password; (4) The client automatically includes the header in all requests for the duration of the exchange. Figure 8 show the conversation as revealed by Fiddler. For a more detailed discussion see http://www.4guysfromrolla.com/articles/031204-1.aspx
Figure 8: HTTP Authorization Conversation
From the PB WCF perspective, your programming job is to set up the credentials for the exchange. The low-level runtime exchange process is handled internally by the infrastructure. A minor challenge is that from the PowerBuilder coding perspective you're navigating into partially uncharted waters. There is no PowerBuilder documentation on the members of the Sybase.PowerBuilder.WCF.Runtim S ybase.PowerBuilder.WCF.Runtime e assembly. However, armed with a basic understanding of WCF and a few minutes to examine the members of the referenced assembly I imagine imagine that you will be able to figure out what to do. Here's the basic algorithm: 1.
2.
3.
In the constructor of your proxy class, instantiate a WebClientCredential object and set your credentials and authentication type into it. Figure 9 shows the WebClientCredential class and its members (it's just a value object). a. Set a value for the AuthenticationMode using a value from the AuthenticationMode AuthenticationMode enumeration. In our case we set the value to Basic! b. Provide your user ID and password. Assign your WebClientCredential object to your WebConnection object. The WebConnection is already instantiated and has the identifier name restConnectionObject. Figure 9 shows this object with the important property. Call your service as usual. Be sure to include exception handling code that tests for the 401 HTTP error.
Figure 9: WebClientCredential class
Listing 3 shows a sample RESTful service configured to use Basic authentication. Collapse | Copy Code
//
vvvvv----Project vvvvv----Pro ject Generated Generated Code----vvvv Code----vvvv
m_service = create PBWebHttp.RestService( "http://phprestsql.sourceforge.net/tutorial/user?firstname={p_first}&sur name={p_last}&email={p_email}&company_uid={p_id}" , PBWebHttp.WebMessageFormat.Xml!, PBWebHttp.WebMessageF PBWebHttp.WebMessageFormat.Xml!) ormat.Xml!) restConnectionObject = create PBWebHttp.WebConnection restConnectionObject.Endpoint = http: //phprestsql.sourceforge.net/tutor //phprestsql.sourcefor ge.net/tutorial/user?fir ial/user?firstname={p_ stname={p_first}&surnam first}&surname={p_last}& e={p_last}&email={p_ email={p_ email}&company_uid={p_id}
restConnectionObject.RequestMessageFormat = PBWebHttp.WebMessageFormat.Xml! restConnectionObject.ResponseMessageFormat = PBWebHttp.WebMessageFormat.Xml! //
vvvvv----Custom vvvvv----Cus tom Authentication Authentication Code----vvvv Code----vvvv
//configure credential credentials s PBWebHttp.WebClientCredential lsCredential lsCredential lsCredential = create PBWebHttp.WebClientCredential PBWebHttp.WebClientCredential lsCredential.AccessAuthentication = PBWebHttp.AuthenticationMode.Basic! lsCredential.Password= 'demo' lsCredential.Username= 'p126371rw' restConnectionObject.ClientCredential = lsCredential //add credentials credentials to connection connection Listing 3
Secure Socket Layer Communication Specifying and handling encrypted communication over a SSL transport is pretty transparent to the application developer. As you can see in Figure 10, all you need to do is specify the HTTPS protocol in the Project Painter Service URL. The handshake and encryption are handled by the underlying infrastructure as shown in Figure 11.
Figure 10: Setting up SSL communication
Figure 11: SSL Handshake
Conclusion In addition to calling service methods, the PowerBuilder client-side developer is responsible for configuring authentication and authorization properties prior to making service calls as w ell writing code to handle server-side errors responses. With a bit of forethought this code can be written in a reusable manner to work in conjunction with project painter-generated proxy classes. With the addition of R ESTful web service client-side infrastructure, PowerBuilder .NET clients can now enjoy the same service-oriented s ervice-oriented interoperability as other .NET languages. Long Live PowerBuilder!
MISC . What is REST?
REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications communications protocol -- and in virtually all cases, the HTTP protocol is used. REST is an architecture style for style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.
In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST -based architecture.
RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations. REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will see how much more simple REST is.
Despite being simple, REST is fully-featured; there's basically nothing you can do in Web Services that can't be done with a RESTful architecture.
REST is not a "standard". There will never be a W3C recommendataion for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often "roll your own" with standard library features in languages like Perl, Java, or C#. BY DR. M. ELKSTEIN 45 COMMENTS
2. REST as Lightweight Web Services As a programming approach, REST is a lightweight alternative to Web Services and RPC. Much like Web Services, a REST service is:
Platform-independent (you don't care if the server is Unix, the client is a Mac, or anything else), Language-independent Language-in dependent (C# can talk to Java, etc.), Standards-based (runs on top of HTTP), and Can easily be used in the presence of firewalls.
Like Web Services, REST offers no built-in security features, encryption, session management, QoS guarantees, etc. But also as with Web Services, these these can be added by building on top of HTTP:
For security, username/password tokens are often used. For encryption, REST can be used on top of HTTPS (secure sockets).
... etc.
One thing that is not part part of a good REST design is cookies: The "ST" in "RE ST" stands for "State Transfer", and indeed, in a good REST design operations are self-contained, and each re quest carries with it (transfers) all the information (state) that the server needs in order to complete it. BY DR. M. ELKSTEIN 9 COMMENTS
3. How Simple is REST? Let's take a simple web service as an a n example: querying a phonebook application for the d etails of a given user. All we have is the user's ID. Using Web Services and SOAP, the request would look something like this: 12345
(The details are not important; this is just an exa mple.) The entire shebang now has to be sent (using an HTTP POST request) to the server. The result is probably an XML file, but it will be embedded, as the "payload", inside a SOAP response envelope. And with REST? The query will probably probably look like this: http://www.acme.com/phonebook/UserDetails/12345
Note that this isn't the request body -- it's just a URL. This URL is sent to the server using a simpler GET request, and the HTTP reply is the raw result data -- not embedded inside anything, just the data you need in a way you can directly use.
It's easy to see why Web Services are often used with libraries that create the SOAP/HTTP request and send it over, and then parse the SOAP response. With REST, a simple network network connection is all you need. You can even even test the API directly, using your browser. Still, REST libraries (for simplifying things) do exist, and we will discuss some of these later.
Note how the URL's "method" part is not called "GetUserDetails", but simply "UserDetails". It is a common convention in REST design to use nouns nouns rather rather than verbs verbs to to denote simpleresources simple resources..
The letter analogy A nice analogy for REST vs. SOAP is mailing a letter: letter: with SOAP, you're using an envelope; with REST, it's it's a postcard. Postcards are easier to handle (by the receiver), waste less paper (i.e., consume less bandwidth), and have a short content. content. (Of course, REST requests requests aren't really limited in length, esp. if they use POST rather than GET.) But don't carry the analogy too far: unlike letters-vs.-postcards, REST is every bit as secure as SOAP. In particular, REST can be carried over secure sockets (using the HTTPS protocol), and content can be encrypted using any mechanism you see fit. Without encryption, REST and SOAP are both insecure; with proper encryption in place, both are equally secure. BY DR. M. ELKSTEIN 16 COMMENTS
4. More Complex REST Requests The previous section included a simple example for a REST request -- with a single parameter. REST can easily handle more complex requests, including multiple parameters. In most cases, you'll just use HTTP GET parameters in the URL. For example: http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe
If you need to pass long parameters, or binary or binary ones, you'd normally use HTTP POST requests, and include the parameters in the POST body. As a rule, GET requests requests should be for read-only queries; they should should not change the state state of the server and its data. For creation, updating, and deleting data, use POST requests. (POST (POST can also be used for readread only queries, as noted above, when complex parameters are required.)
In a way, this web page (like most others) can be viewed as offering services via a REST API; you use a GET request to read data, and a POST request to post a comment -- where more and longer parameters are required.
While REST services might might use XML in their responses responses (as (as one way of organizing structured data), REST requests requests rarely rarely use XML. As shown s hown above, in most cases, request parameters are simple, and there is no need for the overhead of XML.
One advantage of using XML is type safety. However, in a stateless system like REST, you should always always verify verify the validity of your input, XML or otherwise! ****************** END MISC
