overview of restful web services “a complex system that works is invariably found to have evolved...

©SoftMoore Consulting 1

Overview of RESTful Web Services

“A complex system that works is invariably found to have evolved from a simple system that worked.”

– John Gall (Systemantics)

2©SoftMoore Consulting

Approaches to Distributed Processing

• Remote Procedure Call (RPC)– distributed functions

• CORBA/COM/DCOM– distributed objects (language independent)

• Java Remote Method Invocation (RMI)– distributed objects (Java-based)

• XML-RPC and Simple Object Access Protocol (SOAP)– distributed objects over the web (language independent)

• REST– distributed resources over the web


What is a Web Service?

• An approach to using the web for distributed applications

• A software system designed to support interoperable machine-to-machine interaction over a network (W3C)

• An API that can be accessed over web and executed on a remote system hosting the requested service

• Characteristics of web services– communicate using open protocols such as XML, HTTP, etc.– range from such major services as storage management and

CRM to much more limited services such as providing a stock quote and the checking of bids for an auction item.


What is REST?

• REpresentational State Transfer (REST) – an approach to the design of software architectures for distributed hypermedia systems.

• Introduced in 2000 by Roy Fielding (one of the principal authors of HTTP) in his doctoral dissertation

• An architectural style centered around two basic principles:– resources as URIs– operations as HTTP methods

• Not a standard, but based on web standards– URIs, HTTP, HTML, XML, JSON, Atom, RDF, etc.

• Conforming to the REST constraints is often referred to as being “RESTful”.


REST Architectural StyleCharacteristics and Constraints

• Client-server – separation of concerns (e.g., storage versus user interface)

• Stateless – each client request contains all the information necessary to service the request

• Cacheable – improves scalability and performance(Responses can define themselves as being cacheable or not.)

• Uniform interface (more on next slide)

• Layered system – intermediary servers can improve scalability via load balancing and shared caches

• Code on demand (optional) – servers can transfer logic to the client (e.g., JavaScript or Java applets)


Guidelines for REST Interfaces

• Identification of resources using URIs

• Manipulations of resources through representations– Resources are conceptually separate from their representations.– A resource can have more than one representation, although

one is usually designated as the default.

• Self-descriptive messages– Each message includes enough information to describe how to

process the message (e.g., invoke an XML parser).

• Hypermedia as the engine of application state– Related resources are identified in the returned representation;

e.g., via URIs.


Components of a RESTful Web Service

• A base URI for the web service– e.g., http://example.com

• A set of resources with URI names relative to the base– e.g., http://example.com/order/1234

• The MIME types of the data supported by the web service– e.g., XML, JSON, plain text, etc.

• The set of operations supported by the web service using HTTP methods– e.g., POST, GET, PUT, DELETE

HTTP(Hypertext Transfer Protocol)

• Simple, stateless, request/response protocol– client opens connection and sends request message to server– server formulates and returns response message, usually

containing the resource that was requested

• HTTP/1.1 message format– Initial line – three parts, separated by spaces

• Method name (GET, POST, HEAD, PUT, DELETE, etc.)• Local path of the requested resource• Version of HTTP being used (e.g., “HTTP/1.1”)

– Zero or more lines known as headers– A blank line– An optional message body (e.g. a file, query data, etc.)

©SoftMoore Consulting Slide 8

Note: HTTP/2 uses a binary protocol − no longer text-based.

Example: HTTP GET Request

GET /HelloUser.jsp?name=John HTTP/1.1Host: www.softmoore.com:80User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.7) Gecko/20070914 Firefox/2.0.0.7Accept: text/xml,application/xml,application/xhtml+xml, text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5Accept-Language: en-us,en;q=0.5Accept-Encoding: gzip,deflateAccept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7Keep-Alive: 300Connection: keep-alive

©SoftMoore Slide 9

Note: Each header is on a single line (no line breaks).Line breaks are shown above to approve readability.

Accept headers support content negotiation, resultingin possibly different representations of a resource.

Example: HTTPResponse to a GET Method

HTTP/1.1 200 Document followsDate: Tue, 14 Apr 2007 09:25:19 PSTServer: JWS/1.1Last-modified: Mon, 17 Jun 2005 21:53:08 GMTContent-type: text/htmlContent-length: 4435

<4435 bytes worth of data -- the document body>

©SoftMoore Slide 10

Example: HTTP POST Request

POST /servlet/MyServlet HTTP/1.1User-Agent: Mozilla/4.0 (compatible; MSIE 4.01; Windows NT)Host: www.softmoore.com:80Accept: image/gif, image/x-xbitmap, image/jpeg, */Content-type: application/x-www-form-urlencodedContent-length: 39

name=John&company=SoftMoore%20Consulting

©SoftMoore Slide 11

Note: A blank line signals the end of the POST requestheader and the beginning of the extended information.


Using the HTTP GET Method Properly

• The handling of a GET method is expected to be– safe: no side effects– idempotent: can safely be repeated

• Improper use of the HTTP GET methodGET /adduser?name=moore HTTP/1.1Host: www.softmoore.com:80

• Proper use of HTTP – use POST methodPOST /users HTTP/1.1Host: www.softmoore.com:80Content-Type: application/xml

<?xml version="1.0"?><user> <name>moore</name></user>


CRUD/HTTP Mapping

CRUD Task

HTTP Method Action

Create POST Create a resource (without an ID)

Read GETRead a resource(no side effects, possibly cached)

Update PUTUpdate (or possibly create) a resource with an ID

Delete DELETE Delete a resource


Resources Versus Representations

• A resource can be essentially any coherent and meaningful abstraction that may be addressed.

• A representation of a resource is typically a document that captures the current or intended state of a resource.

• A resource can have more than one representation – XML, JSON, PDF file, JPEG image, etc.


Examples: Different Representations

• XML

• JSON

<?xml version="1.0"?><customer> <name>John Moore</name> <phone>123-456-7890</phone> <city>Charleston</city> <state>SC</state></customer>

{ "customer" : { "name" : "John Moore", "phone" : "123-45-6789", "city" : "Charleston", "state" : "SC" }}


Basic Principles of REST

• Resources are identified by URIs. (Think URLs.)– URI “/” means parent-child or whole-part relationship (tree-like)– provide data to clients via gradual unfolding

http://example.com/products/1234/reviews

• Clients communicate with resources via requests using a standard set of methods based on HTTP.

• Resources are manipulated through their representations, identified by media types.

• Responses can contain URIs that link to further resources.


Using URI’s to Name Resources

• http://example.com/customers– all customers

• http://example.com/orders/– all orders

• http://example.com/customers/1234– customer with id 1234

• http://example.com/orders/5678– order with id 5678

• http://example.com/customers/1234/orders– all orders for customer with id 1234

• http://example.com/customers?last-name=moore– list of all customers with a last name of moore


Examples: Using HTTP Methods

URIHTTP

MethodAction

http://example.com/customers POST

Create a new customer. The ID is assigned by the service and is usually returned as part of the data returned by this operation.

http://example.com/customers GETRetrieve a list of all customers with their member URIs for further navigation.

http://example.com/customers/1234 PUTUpdate (or possibly create) data for customer with ID 1234

http://example.com/customers/1234 GETRetrieve a representation for the customer with ID 1234

http://example.com/customers/1234 DELETE Delete customer with ID 1234


REST Anti-Patterns(Stefan Tilkov)

• Tunneling everything through GET or POST

• Ignoring caching

• Ignoring response codes

• Misusing cookies (e.g., to manage client sessions)

• Forgetting hypermedia

• Ignoring MIME types

• Breaking self-descriptiveness


“Big” Web Services versus RESTful Web Services

• “Big” Web Services are based on SOAP and WS-*– heavyweight– have little to do with the web other than as a transport– disregards many HTTP capabilities such as authentication,

caching, content type negotiation, etc.– designed to operate from a single URI with methods being

invoked from within the request payload– expose internal algorithms through a complex programming-

language-like interface that’s different for every service– mostly about invoking behavior


“Big” Web Services versus RESTful Web Services(continued)

• RESTful web services are based on HTTP and URI’s– lightweight– designed to take advantage of the web and HTTP– expose data through a simple document-processing interface

that is always the same– HTTP methods invoke behavior on resources accessed via URIs– mostly about managing information– not appropriate for every distributed application


Impact of REST

Key evidence of this shift in interface design is the adoption ofREST by mainstream Web 2.0 service providers – includingYahoo, Google, and Facebook – who have deprecated orpassed on SOAP and WSDL-based interfaces in favor of aneasier-to-use, resource-oriented model to expose their services....If measured by the number of Web services that use it, RESThas emerged in the last few years alone as a predominant Webservice design model. In fact, REST has had such a large impacton the Web that it has mostly displaced SOAP- and WSDL-basedinterface design because it's a considerably simpler style to use.

– Alex Rodriquez (IBM Software Engineer)


REST Framework Implementations

• Restlet (www.restlet.org)

• Java Specification Request (JSR) 311: JAX-RS: The Java API for RESTful Web Services– reference implementation is Jersey (https://jersey.dev.java.net/)

• Apache Sling

• Microsoft's Azure Services

• Python RIP

• Ruby On Rails

• PHP Symfony, Zend Framework

• Perl Catalyst REST

https://jersey.dev.java.net/


References

• RESTFul Web Services by Leonard Richardson and Sam Ruby, O’Reilly Media, 2007.

• RESTful Java with JAX-RS 2.0 (Second Edition), Bill Burke, O’Reilly Media, 2013

• Building RESTful Web Services with JAX-RShttps://docs.oracle.com/javaee/7/tutorial/jaxrs.htm

• “Representational State Transfer,” Wikipedia article.https://en.wikipedia.org/wiki/Representational_state_transfer

• “RESTful Web Services: The Basics” by Alex Rodriguez, IBM developerWorks article, 2008.http://www.ibm.com/developerworks/webservices/library/ws-restful/

https://docs.oracle.com/javaee/7/tutorial/jaxrs.htm

https://en.wikipedia.org/wiki/Representational_state_transfer

https://en.wikipedia.org/wiki/Representational_state_transfer

http://www.ibm.com/developerworks/webservices/library/ws-restful/

overview of restful web services “a complex system that works is invariably found to have evolved...

Documents