Architectural Styles

SOAP and REST are two important Software architectures and Richardson Maturity Model helps to identify them.

Richardson maturity model

This is a measurement of how closely a system embrace different pieces of Web Technology:

  • Information resources,

  • HTTP as an application protocol,

  • Hypermedia as the medium of control.

Levels

There are 4 levels:

Level 0

This is basically where SOAP is.

  • There are no information resources
  • HTTP is treated like a transport protocol instead of an application protocol
  • There is no concept of hypermedia.
Level 1
  • URLs are used, but not always as appropriate information resources and everything is usually a GET request (including requests that update server state)
  • There is no concept of hypermedia.
Level 2

This is where most Internet-facing REST web services are because they only support non-hypermedia formats.

  • URLs are used to represent information resources
  • HTTP is respected as an application protocol sometimes including content negotiation
  • There is no concept of hypermedia.
Lever 3
  • URLs are used to represent information resources.
  • HTTP is respected as an application protocol including content negotiation.
  • Hypermedia drivers the interactions for clients.

SOAP

Originally defined as a Simple Object Access Protocol, it is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks.

SOAP is best leveraged when the lifecycle of a request cannot be maintained in the scope of a single transaction because of technological, organizational or procedural complications.

It relies on XML for its message format, and usually relies on other Application Layer protocols, most notably RPC and HTTP, for message negotiation and transmission.

SOAP can form the foundation layer of a web services protocol stack, providing a basic messaging framework upon which web services can be built. This XML based protocol consists of three parts:

  • an envelope, which defines what is in the message and how to process it
  • a set of encoding rules for expressing instances of application-defined datatypes
  • and a convention for representing procedure calls and responses.



RESTful service

REST stand for Representational State Transfer, and it is an architectural style. It helps to create well-designed scalable distributed application resilient to change.

REST uses:

  • identification of resources
  • manipulation of resources through representations
  • self-descriptive messages
  • hypermedia as the engine of application state.

Conforming to the REST constraints is referred to as being RESTful.

REST is not limited to the HTTP protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for application based on the transfer of meaningful representational state.

RESTful applications maximize the use of the pre-existing, well-defined interfaces. In HTTP REST utilizes these existing features of the HTTP protocol to allows caching and security enforcement.

MORE_ABOUT Application Layer (see http://homepages.uel.ac.uk/u0110988/page2.htm)

Rest defines how pieces of the Web Technology should be used.

In specific we have:

  • URL should be used to represent name of resources of information. For instance resolving the URL we can obtain

    • the actual resource
    • a reference to information about a particular resource
    • the result of a servlet computation.
    Content negotiation

    It is a HTTP ability by which you can ask for information in different forms (e.g. curl -H "Accept:application/json" http://puglieseweb.com .)

    Note that there is a separation of the name of the name representing the resource and its form the information is returned.

  • HTTP should be used as an application protocol instead of a general transport protocol
  • non-hypermedia or hypermedia formats used as the medium of control.
Information resources are manipulated by four 4 HTTP verbs (or methods)
This four HTTP methods act on the represented named resources and REST defines explicitly and clearly their specific behaviours.

This allows the clients to be self-empowered to make decisions in the face of network interruptions and failure (e.g. If a client is interrupted while it is making a GET request, it should be empowered to issue it again.)

Each request contains enough state to answer the request
This is an important aspect of RESTful request that allows for the conditions of visibility and statelessness on the server.

REST approach clearly distinguish between:

GET

Actions which make no change and thus may be cached or repeated (GET).

That implies that GET should be a (1) Saferequest==> do not modify anything on the server side. GET request transfers representations of named resources from a server to a client. The client gets back a bytestream tagged with metadata that indicates how the client should interpret it. GET are also intended to be (2) idempotent: issuing a request more than once will have no consequences.

actions which make a change but may be casually repeated without problems (PUT, DELETE)

PUT

PUT is not supported by HTML forms. PUT is idempotent. It is used when the client has a URL reference to an existing resource and wishes to update it changing the state of the application.

PUT can be used to create a resource if the client is able to predict the resource's identity. This happen in the case the client is in control of the server side information spaces. Publishing into a user's weblog space is a typical example of PUTing to a user-specified name.

DELETE

DELETE verb is typically used for information spaces we control. PUT is intended to be idempotent. We should build requests by failing silently and returning a 200 even if it has already been deleted.

POST
actions which should neither be repeated nor cached.

We have a a side effect each time POST is executed.

POST is neither safe nor idempotent.

POST is used when the client cannot predict the identity of the resource it is requesting (for example if we want to create a new resource). So we POST a representation of the resource to handle (e.g. selvlet)

When we POST a new resource, upon successful processing, from the server we should return a 201 HTTP response code with a Location header indication the location of the newly created resource (not) the short 200 HTTP response and the body of the created resource). It can avoid a second request, but it conflates GET and SET and complicate the caching of the resource.

POST can be used to append (a partial update) new item in an order or a cart

POST can be used to submit queries either as a representation of a query or URL-encoded form values. In this case it is usually fair to return results directly from this kind of a POST since there is no identity association with the query.

This in turn enables intermediate software (be it in the form of libraries, reusable components, or entirely separate systems)to implement sensible optimisation and error-handling strategies without needing knowledge of the contentor relationships of the resources

REST is best used to manage systems by decoupling the information that is produced and consumed from the technologies that do so.

It is possible to achieve the architectural properties of:

Statelessness
  • Every request is totally isolated from other requests
  • The server does not know about the client previous operations
  • The application state is stored on the client.

This in turn enables intermediate software (be it in the form of libraries, reusable components, or entirely separate systems) to implement sensible optimisation and error-handling strategies without needing knowledge of the content or relationships of the resources.

Addressability

Every interesting aspect of the application dataset is exposed by URI.

Addressability can also help in caching for better performance.

http://www.google.com/search?q=java

Create RESTful URLs

General principles for good URI design:

  • Don't use query parameters to alter state
  • Don't use mixed-case paths if you can help it; lowercase is best
  • Don't use implementation-specific extensions in your URIs (.php, .py, .pl, etc.)
  • Don't fall into RPC with your URIs
  • Do limit your URI space as much as possible
  • Do keep path segments short
  • Do prefer either /resource or /resource/; create 301 redirects from the one you don't use
  • Do use query parameters for sub-selection of a resource; i.e. pagination, search queries
  • Do move stuff out of the URI that should be in an HTTP header or a body

(Note: I did not say "RESTful URI design"; URIs are essentially opaque in REST.)

General principles for HTTP method choice:

  • Don't ever use GET to alter state; this is a great way to have the Googlebot ruin your day
  • Don't use PUT unless you are updating an entire resource
  • Don't use PUT unless you can also legitimately do a GET on the same URI
  • Don't use POST to retrieve information that is long-lived or that might be reasonable to cache
  • Don't perform an operation that is not idempotent with PUT
  • Do use GET for as much as possible
  • Do use POST in preference to PUT when in doubt
  • Do use POST whenever you have to do something that feels RPC-like
  • Do use PUT for classes of resources that are larger or hierarchical
  • Do use DELETE in preference to POST to remove resources
  • Do use GET for things like calculations, unless your input is large, in which case use POST

General principles of web service design with HTTP:

  • Don't put metadata in the body of a response that should be in a header
  • Don't put metadata in a separate resource unless including it would create significant overhead
  • Do use the appropriate status code
    • 201 Created after creating a resource; resource must exist at the time the response is sent
    • 202 Accepted after performing an operation successfully or creating a resource asynchronously
    • 400 Bad Request when someone does an operation on data that's clearly bogus; for your application this could be a validation error; generally reserve 500 for uncaught exceptions
    • 403 Forbidden when someone accesses your API in a way that might be malicious or if they aren't authorized
    • 405 Method Not Allowed when someone uses POST when they should have used PUT, etc
    • 413 Request Entity Too Large when someone does something like ask for your entire database
    • 418 I'm a teapot when attempting to brew coffee with a teapot
  • Do use caching headers whenever you can
    • ETag headers are good when you can easily reduce a resource to a hash value
    • Last-Modified should indicate to you that keeping around a timestamp of when resources are updated is a good idea
    • Cache-Control and Expires should be given sensible values
  • Do everything you can to honor caching headers in a request (If-None-Modified, If-Modified-Since)
  • Do use redirects when they make sense, but these should be rare for a web service

With regard to your specific question, POST should be used for #4 and #5. These operations fall under the "RPC-like" guideline above. For #5, remember that POST does not necessarily have to use Content-Type: application/x-www-form-urlencoded . This could just as easily be a JSON or CSV payload.

REST VS CRUD

  1. Def: A side effect can be a change in the database

    1. REST put VS CRUD UPDATE(implies a side effect)

Put supplies a resource to an URI:

  • invalid URI ==> put fails

  • URI contains no resources ==> resources is placed there;

  • URI contains different resources ==> resources is replaced.

  • URI contains the same resources ==> no apparent change

UPDATE ==> update existingrecords in a database

  1. REST post VS CRUD CREATE(implies a side effect)

post: ==> resource change or side effect each time it is executed

examples:1) Sending an email; 2) post implemented by either SQL INSERT or SQL UPDATE that modify the value)

CREATE:

  • explicitly creates a new resource , and

  • is undefined if that resource already exists.

Right approach rules:

The following approach has the big advantage that the impact of an accidental re-postis minimised. In a well designed system, the creating of a new URI could be as low-impact as incrementing an integer, only requiring storage of resource dataif/when it is later populated using put.

  1. a post should be simple and quick, leaving the way for future changes using put as soon as possible.

  2. For example, to create and populate a new resource in REST it is typical to

  • call post on some parent resource which results in the

  • return of, or redirect to, a new (empty) URI, and then

  • populate the URI with one or more put operations.

  1. REST get VS CRUD read

get: fetches a singleresource (ex. Loading an image)

read: return a set of records form a database (SELECT operation)

  1. REST delete VS CRUD DELETE

delete: simple delete of a resource at a singleURI

DELETE: ability to do complexdeletes on a database



Resources:

http ://blog.punchbarrel.com/2008/10/31/rest-is-not-crud-and-heres-why/

<formid="quick-search"method="get">

<fieldsetclass="search">

<labelfor="qsearch">Search:</label>

<inputclass="tbox"id="search"

type="text"name="qsearch"value="Search..."

title="Start typing and hit ENTER"/>

<buttontype="submit"class="btn"title="Submit Search">Search</button>

</fieldset>

</form>



<formaction="/_ah/plugin/form/send"method="POST"id="form-feedback">

<inputtype="hidden"value="feedback"name="form-name">

<label>Name</label>

<inputtype="text"size="20"value=""name="name">

<label>Email</label>

<inputtype="text"size="20"value=""name="email">

<label>Message</label>Introduction to the Build Lifecycle



The Maven Release Plugin

<textareacols="60"rows="10"name="message"></textarea>

<inputtype="submit"value="Send">

</form>

  1. REST or RPC?

I was wondering if one choses AutoBean with JSON (instead of RequestFactory) to achieve higher loose coupling in a RESTful architecture (to completely decouple client and server), what would be the downside to this approach ?


AutoBean/Editor/EntityProxy/ServiceLayer/EntityChangeEvent

JSON/REST vs EntityProxy/RequestFactory

and how AutoBean fits into all this.

Thank you for the hard work.