Communication Protocols And Web Services

Communication Protocols and Web ServicesCreated by Omer Katz, 2010Omer Katz © Some Rights Reserved

Structure of a standard networkingstack for the Web

Common serialization formatsJSONNatively supported within JavaScriptCapable of referencing other records by conventionHuman readable formatLightweightEasy to parseUses JSON-Schema to validate itselfKey-Value based syntaxXMLJavaScript exposes a proprietary DOM APIHuman readable format for hierarchal dataHard to parseConsumes more memory than JSONSupports XSLT and XPathUses XML-Schema or DTD to validate itselfMarkup based syntax

What is a web service?A web service is typically an application programming interface (API) or Web API that is accessed via Hypertext Transfer Protocol (HTTP) and executed on a remote system, hosting the requested service.Web services do not provide the user with a GUI.Web services instead share business logic, data and processes through a programmatic interface across a network. Developers can then add the Web service to a GUI (such as a Web page or an executable program) to offer specific functionality to users.

Web services communication protocolsRPCXML-RPCHTTP BoundJSON-RPCSMD – Service Mapping DescriptionJSONPAllows cross domain Ajax requestsSOASOAPXML BasedStrongly typedWSDL dependantRESTStatelessCacheableCode On DemandClient and Server are unaware of each other’s stateLayered SystemUniform InterfaceService may be described through SMD, WSDL, WADL or not at all

What is RPC?Remote Procedure Call.Allows to access server-side/inter-process operations from a client through a well-defined protocol.Examples: COBRA, XML-RPC, JSON-RPC, DCOM, RMIClient is tightly coupled with the server

JSON-RPCRequest/Response modelRequestNotificationResponseErrorBatch operationsAdvantagesLightweightJSON-Schemas can be extended to validate specific messageNot bound to HTTP by the specification, but might be used with itCan be natively serialized from within JavaScriptService discovery can be achieved through SMD or WADLDisadvantagesProceduralThe web service's methods grow linearly with the number of client request typesNot bound to a URIConclusionFits for low resources environment (embedded devices)Does not fit for rapidly growing web servicesDoes not fit for web services operating on many entities unless the web service is an HTTP service

JSON-RPC ExamplesA Notification:{ ”jsonrpc”: ”2.0”, ”method”: ”update”, ”params”: [1,2,3,4,5] }

JSON-RPC ExamplesA Request{ ”jsonrpc”: ”2.0”, ”method”: ”subtract”, ”params”: { ”subtrahend”: 23, ”minuend”: 42 }, ”id”: 3 }

JSON-RPC ExamplesAn Error:{ ”jsonrpc”: ”2.0”, ”error”: { ”code”: -32601, ”message”: ”Procedure not found.” }, ”id”: ”1”}

JSON-RPC ExamplesBatch Request:[{ ”jsonrpc”: ”2.0”, ”method”: ”sum”, ”params”: [1,2,4], ”id”: ”1” },{ ”jsonrpc”: ”2.0”, ”method”: ”notify_hello”, ”params”: [7] },{ ”jsonrpc”: ”2.0”, ”method”: ”subtract”, ”params”: [42,23], ”id”: ”2” }]

JSON-RPC ExamplesBatch Response:[ { ”jsonrpc”:”2.0”, ”result”:7, ”id”:”1” }, { ”jsonrpc”:”2.0”, ”result”:19, ”id”:”2 },{ ”jsonrpc”:”2.0”, ”error”:{ ”code”:-32601, ”message”:” Procedure not found.” }, ”id”:”5” },]

XML-RPCRequest/Response modelRequestResponseErrorAdvantagesBound to a URICan represent hierarchical data in a readable wayXSLT & XPathCan be validated through XML-Schema or DTDDisadvantagesProceduralThe web service's methods grow linearly with the number of client request typesBound to HTTPOnly appropriate for the webHard to parseHeavy payloadConsumes a lot of memoryNo bulk operationsConclusionDoes not fit for rapidly growing web servicesDoes not fit for embedded devicesFits to represent hierarchical data

XML-RPC ExamplesRequest: <?xml version=”1.0”?><methodCall> <methodName>examples.getStateName</methodName> <params> <param> <value> <i4>40</i4> </value> </param> </params></methodCall>

XML-RPC ExamplesResponse:<?xml version=”1.0”?> <methodResponse> <params><param> <value> <string>South Dakota</string> </value> </param> </params> </methodResponse>

XML-RPC ExamplesError:<?xml version=”1.0”?> <methodResponse> <fault> <value> <struct> <member><name>faultCode</name> <value><int>4</int></value> </member> <member> <name>faultString</name> <value><string>Too many parameters.</string></value> </member> </struct> </value> </fault></methodResponse>

What is SOA?Service Oriented Architecture.Allows to access server-side from a client through a well-defined protocol.Examples: SOAP, REST, SOAPjrClient does not have to be tightly coupled with the server.Unlike RPC based web services which usually are not discoverable there is a way to discover services in SOA based web service.

Service Description StandardsWSDLWeb Services Description LanguageWell knownVerboseUses XMLNot human readableUsed by WCFFeels natural for SOAP servicesEndorsed by MicrosoftWSDL 1.1 supports only GET and POST requests

Service Description Standards - ContinuedWADLWeb Application Description LanguageNot very well knownA bit less verbose than WSDLUses XMLA bit more human readableUsed by JavaFeels natural for REST ServicesEndorsed by Sun Microsystems

Service Description Standards - ContinuedSMDService Mapping Description Working Draft statusLess verboseUses JSONHuman readableUsed by the Dojo ToolkitNot stableEndorsed by Sitepen and The Dojo Foundation

WSDL Example<description> <types> <schema> <element name=”myMethod”> <complexType> <sequence> <element name=”x” type=”xsd:int”/> <element name=”y” type=”xsd:float”/> </sequence> </complexType> </element> <element name=”myMethodResponse”> <complexType/> </element> </schema></types>…

WSDL Example <message name=”myMethodRequest”> <part name=”parameters” element=”myMethod”/></message><message name=”empty”> <part name=”parameters” element=”myMethodResponse”/></message><portTypename=”PT”> <operation name=”myMethod”> <input message=”myMethodRequest”/> <output message=”empty”/> </operation></portType>Hold your horses, there’s more…

WSDL Example <binding interface=”...”>  </binding> <service interface=”...”>  <endpoint binding=”...” address=”...”/> </service></description>And it goes on and on… I actually tried to keep it short.

Have I already mentioned that WSDL is verbose?

SMD Example{ target:”/jsonrpc”, // this defines the URL to connect for the services transport:”POST”, // We will use POST as the transport envelope:”JSON-RPC-1.2”, // We will use JSON-RPC SMDVersion:”2.0”, services: { add : { // define a service to add two numbers parameters: [ {name:”a”,type:”number”}, // define the two parameters {name:”b”,type:”number”}], returns:{”type”:”number”} }, foo : { // nothing is required to be defined, all definitions are optional. //This service has nothing defined so it can take any parameters //and return any value }, getNews : { // we can redefine the target, transport, and envelope for specific services target: ”/newsSearch”, transport: ”GET”, envelope: ”URL”, parameters:[ { name: ”query”, type: ”string”, optional: false, default: ”” } ], returns:{type:”array”} }}

But that’s not even a standard yet

WADL Example<application xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation=http://research.sun.com/wadl/2006/10 wadl.xsd xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:ex=http://www.example.org/types xmlns=http://research.sun.com/wadl/2006/10> <grammars> <include href=ticker.xsd/> </grammars>…

WADL Example<resources base=http://www.example.org/services/> <resource path=getStockQuote> <method name=GET> <request> <paramname=symbol style=query type=xsd:string/> </request> <response> <representation mediaType=application/xml element=ex:quoteResponse/> <fault status=400 mediaType=application/xml element=ex:error/> </response> </method> </resource> <! many other URIs> </resources></application>

Looks a bit better, but it’s not widely adopted.So what do we do?

Service Discovery - SummeryUse whatever your platform allows you (WSDL for .NET, WADL for JAVA and SMD for Dojo)Don’t allow service discovery – this may happen if: You intend the web service to be used only internally.You are not using a tool to generate a proxy.You intend the web service to always be on a fixed IPAllow gradual service discoveryEach call will expose different operations that are availableOccasionally adds an unnecessary overheadCan be solved using a parameter in the request to turn off and on gradual discoveryOnly exposes a part of the service that is related to the call

Service Discovery – WS-DiscoveryWeb Services Dynamic DiscoveryA multicast discovery protocol that allows to locate web services over local networkUses web services standards like SOAP

SOAPSimple Object Access ProtocolMessage model:RequestResponseErrorAdvantages:Type safeWCF support feels more naturalMore appropriate for event driven use casesServices are discoverableCan carry any kind of dataDisadvantages:VerboseWSDLHeavy payload, especially over HTTPDoes not fit for streamingHTTP already knows how to handle requests/responsesAccessing from a non-WCF client is nearly impossibleUses XML for the envelope, which makes the possibility to send any kind of data pretty much obsoleteConclusionMajor pain in the ass

SOAP ExampleSOAP RequestPOST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn<?xml version=”1.0”?><soap:Envelopexmlns:soap=”http://www.w3.org/2001/12/soap-envelope” soap:encodingStyle=”http://www.w3.org/2001/12/soap-encoding”><soap:Bodyxmlns:m=”http://www.example.org/stock”> <m:GetStockPrice> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body></soap:Envelope>

SOAP ExampleSOAP ResponseHTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn<?xml version=”1.0”?><soap:Envelopexmlns:soap=”http://www.w3.org/2001/12/soap-envelope” soap:encodingStyle=”http://www.w3.org/2001/12/soap-encoding”> <soap:Bodyxmlns:m=”http://www.example.org/stock”> <m:GetStockPriceResponse> <m:Price>34.5</m:Price> </m:GetStockPriceResponse> </soap:Body></soap:Envelope>

Oh dear, take this abomination away

RESTRepresentational State TransferConstrainsStatelessUniform InterfaceLayered SystemCacheableCode On Demand (Optional)Guiding principlesIdentification of resourcesManipulation of resources through these representationsSelf-descriptive messagesHypermedia As The Engine Of Application State (HATEOAS)

REST is an architecture, not a standard.This means we relay on whatever application protocol we have to use.

REST is not bound to HTTP but feels natural with HTTP

REST – Web ServicesA RESTful web service is implemented over HTTPURI – Unique Resource IdentifierProvides unified interface to access resources./Foos/ - A collection of resources/Foos/[Identifier]/ - An object instance inside a collectionUses HTTP VerbsGETUsed to get content, no side effects are guaranteedPOSTUsed to update contentPUTUsed to create/replace contentDELETEUsed to delete contentOPTIONSHEADDiscoverable through OPTIONS and HEAD VerbsAllows request to refer to different representation through MIME-typesResponds with HTTP Status Codes

Hands On – A Simple RESTful Web Service using ASP.NET MVCWe’re going to write a simple blog applicationWhy ASP.NET MVC?Easy to implementAppropriate for small servicesWhat are our entities?A PostA TagA CommentA UserBoth tags and comments entities are sub-entities of a postBoth posts and comments entities are sub-entities of a user

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe URI Scheme:To represent a resource collection of posts: /Posts/To represent a specific post resource: /Posts/[id]/To represent a resource collection of comments of a specific post resource: /Posts/[id]/Comments/To represent a specific comment resource of a specific post resource: /Posts/[id]/Comments/[commentId]Well, you got the idea, right?How to implement:Go to your Global.asax fileDefine the routesUse constrains to avoid routes clashesUse constrains to define allowed HTTP Verbs

Hands On – A Simple RESTful Web Service using ASP.NET MVCImplementing the URI Scheme:publicstaticvoidRegisterRoutes(RouteCollection routes) { // …routes.MapRoute(”DeleteComment”, ”Comments/{commentId}/”,new { controller = ”Comments”, action = ”Delete” },new { commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”DELETE”) });routes.MapRoute(”EditComment”, ”Comments/{commentId}/”,new { controller = ”Comments”, action = ”Edit” },new { commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”PUT”) }); routes.MapRoute(”AddPostComment”, ”Posts/{postId}/Comments/”,new { controller = ”Comments”, action = ”Add” },new { postId = @”\d+”, httpMethod = newHttpMethodConstraint(”POST”) }); routes.MapRoute(”PostComment”, ”Posts/{postId}/Comments/{commentId}/”,new { controller = ”Comments”, action = ”PostComment” },new { postId = @”\d+”, commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”GET”) }); routes.MapRoute(”PostComments”, ”Posts/{postId}/Comments/”,new { controller = ”Comments”, action = ”PostComments” },new { postId = @”\d+”, httpMethod = newHttpMethodConstraint(”GET”) });routes.MapRoute(”Comment”, ”Comments/{commentId}”,new { controller = ”Comments”, action = ”Comment” },new { commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”GET”) }); routes.MapRoute(”UserComments”, ”Users/{user}/Comments/”,new { controller = ”Comments”, action = ”UserComments” },new { user = @”^[a-zA-Z0-9_]*$”, httpMethod = newHttpMethodConstraint(”GET”) }); routes.MapRoute(”UserComment”, ”Users/{user}/Comments/{commentId}/”, new { controller = ”Comments”, action = ”UserComment” }, new { user = @”^[a-zA-Z0-9_]*$”, httpMethod = newHttpMethodConstraint(”GET”) }); // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe URI Scheme - Explained:Defines a route that maps to an action that allows to delete a commentcommentId is limited to integral values (for more information, read about Regular Expressions)You can reach to this action only by a DELETE requestpublicstaticvoidRegisterRoutes(RouteCollection routes) { // …routes.MapRoute(”DeleteComment”, ”Comments/{commentId}/”,new { controller = ”Comments”, action = ”Delete” },new { commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”DELETE”) }); // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe URI Scheme - Explained:Defines a route that maps to an action that allows to edit a commentcommentId is limited to integral valuesYou can reach to this action only by a PUT requestWhy are we using PUT instead of POST?The Comments/{commentId}/ URI refers to a specific item in a collection, since we are not sending only what is updated in our request we prefer to replace the resource instead of updating itpublicstaticvoidRegisterRoutes(RouteCollection routes) { // …routes.MapRoute(”EditComment”, ”Comments/{commentId}/”,new { controller = ”Comments”, action = ”Edit” },new { commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”PUT”) }); // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe URI Scheme - Explained:Defines a route that maps to an action that allows to add a comment to a postpostId is limited to integral valuesYou can reach to this action only by a POST requestWhy are we using POST instead of PUT?The Posts/{postId}/Comments/ URI refers to a collection, PUT will replace all of our existing comments with a new onePOST only updates a resource, so a new comment is added to our existing comments collectionpublicstaticvoidRegisterRoutes(RouteCollection routes) { // …routes.MapRoute(”AddPostComment”, ”Posts/{postId}/Comments/”,new { controller = ”Comments”, action = ”Add” },new { postId = @”\d+”, httpMethod = newHttpMethodConstraint(”POST”) }); // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe URI Scheme - Explained:Those are the routes we are familiar with, the ones that use GET requests and most of the time return HTMLIn this example, this route maps to an action that allows us to access a specific comment on a postpublicstaticvoidRegisterRoutes(RouteCollection routes) { // … routes.MapRoute(”PostComment”, ”Posts/{postId}/Comments/{commentId}/”,new { controller = ”Comments”, action = ”PostComment” },new { postId = @”\d+”, commentId = @”\d+”, httpMethod = newHttpMethodConstraint(”GET”) }); // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCThe comments controller:Now that our routes are defined we know what actions we need to implementAll actions should use valid HTTP Status CodesAll actions must be able to represent themselves in different formats (JSON, XML, HTML, RSS etc.)How to implement:Create a new controller called CommentsControllerFollow your routing scheme and create the needed actionsCreate a new action result decorator that allows you to select the HTTP Status codeUse attributes to define allowed content types and HTTP Verbs

Hands On – A Simple RESTful Web Service using ASP.NET MVCImplementing the comments controller:publicclassCommentsController : Controller { // … [AcceptVerbs(HttpVerbs.Delete)] // Or [HttpDelete] if you are using MVC 2 and above publicActionResult Delete(intcommentId) { // Delete operation occurs here returnnewHttpResponseCodeActionResultDecorator(204); // 204 No content } [AcceptVerbs(HttpVerbs.Post)] // Or [HttpPost] if you are using MVC 2 and above publicActionResult Add(intpostId) { // Create a new comment that belongs to a post with a post Id of postIdreturnJson(new {CommentId = newCommentId}) ; } [AcceptVerbs(HttpVerbs.Put)] // Or [HttpPut] if you are using MVC 2 and above publicActionResult Add(intcommentId) { // Create a new comment that belongs to a post with a post Id of postIdreturnnewHttpResponseCodeActionResultDecorator(201, Json(new {CommentId = newCommentId}) ); // 201 - Created } // …}

Hands On – A Simple RESTful Web Service using ASP.NET MVCImplementing the HttpResponseCodeActionResultDecorator:publicclassHttpResponseCodeActionResultDecorator : ActionResult{ privatereadonlyintstatusCode; privatereadonlyActionResultactionResult; publicHttpResponseCodeActionResultDecorator(intstatusCode) { this.statusCode = statusCode; } publicHttpResponseCodeActionResultDecorator(intstatusCode, ActionResultactionResult) : this(statusCode) { this.actionResult = actionResult; } publicoverridevoidExecuteResult(ControllerContext context) { context.HttpContext.Response.StatusCode = statusCode;if(actionResult != null) actionResult.ExecuteResult(context); } }

Hands On – A Simple RESTful Web Service using ASP.NET MVCResources with multiple representations:Our list of posts should be representable through RSS and Atom feeds but also display them as HTML.An HTTP request containing an Accept header with a value other than application/rss+xml, application/atom+xml, text/html or application/xhtml+xml will return the HTTP response code “406 Not Acceptable”.The implementation is not trivialAn example of an implementation can be seen here: http://aleembawany.com/2009/03/27/aspnet-mvc-create-easy-rest-api-with-json-and-xmlhowever it does not conform to HTTP due to the fact that it will either return 404 or the default view.How to implement:Create an ActionResult class that inspects the request’s Accept header and executes the requested ActionResult or return 406 Not Acceptable

Hands On – A Simple RESTful Web Service using ASP.NET MVCImplementing the AcceptTypeResult:publicclassAcceptTypeResult : ActionResult{ privatereadonlyint?successStatusCode; private readonly object result; publicAcceptTypeResult(objectresult) { this.result = result; } publicAcceptTypeResult(intsuccessStatusCode, object result) : this(result) { this.successStatusCode = successStatusCode; } publicoverridevoidExecuteResult(ControllerContext context) {var request = context.HttpContext.Request; context.HttpContext.Response.StatusCode = successStatusCode ?? 200;if (request.AcceptTypes.Contains(“application/rss+xml”))Rss(result).ExecuteResult(context);else if (request.AcceptTypes.Contains(“application/atom+xml”))Atom(result).ExecuteResult(context);else if (request.AcceptTypes.Contains(“application/xhtml+xml”) || request.AcceptTypes.Contains(“text/html”))View(result).ExecuteResult(context);else context.HttpContext.Response.StatusCode= 406; } }

Bibliographyhttp://www.infoq.com/articles/webber-rest-workflowhttp://www.infoq.com/articles/mark-baker-hypermediahttp://barelyenough.org/blog/2007/05/hypermedia-as-the-engine-of-application-state/http://third-bit.com/blog/archives/1746.htmlhttp://www.learnxpress.com/create-restful-wcf-service-api-step-by-step-guide.htmlhttp://www.infoq.com/articles/rest-soap-when-to-use-eachhttp://www.prescod.net/rest/http://www.prescod.net/rest/rest_vs_soap_overview/http://www.devx.com/DevX/Article/8155http://tomayko.com/writings/rest-to-my-wifehttp://en.wikipedia.org/wiki/Representational_State_Transferhttp://en.wikipedia.org/wiki/HATEOAShttp://en.wikipedia.org/wiki/SOAPhttp://en.wikipedia.org/wiki/SOAhttp://en.wikipedia.org/wiki/Web_Application_Description_Languagehttp://en.wikipedia.org/wiki/WSDLhttp://en.wikipedia.org/wiki/JSON-RPChttp://en.wikipedia.org/wiki/XML-RPChttp://www.sitepen.com/blog/2008/03/19/pluggable-web-services-with-smd/

For further readinghttp://jcalcote.wordpress.com/2009/08/10/restful-authentication/http://jcalcote.wordpress.com/2009/08/06/restful-transactions/http://www.artima.com/lejava/articles/why_put_and_delete.htmlhttp://www.markbaker.ca/2002/08/HowContainersWork/http://www.w3.org/Protocols/rfc2616/rfc2616.htmlhttp://www.elharo.com/blog/software-development/web-development/2005/12/08/post-vs-put/http://blog.whatfettle.com/2006/08/14/so-which-crud-operation-is-http-post/http://cafe.elharo.com/web/why-rest-failed/http://en.wikipedia.org/wiki/Windows_Communication_Foundation

Communication Protocols And Web Services

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Communication Protocols And Web Services (20)

Recently uploaded (20)

Communication Protocols And Web Services