Scribd
Upload
118 views

Primer

Uploaded by

Brittany Hatcher
Copyright
© © All Rights Reserved
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
118 views

Primer

Uploaded by

Brittany Hatcher
Copyright
© © All Rights Reserved
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
You are on page 1/ 2

///////////////////////////////////////////////////////////////

* Licensed to the Apache Software Foundation (ASF) under one


* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
///////////////////////////////////////////////////////////////

[[library-rest-client-primer, HATEOAS Primer]]


= ReST - HATEOAS Primer

The Polygene™ ReST Client implements HATEOAS (Hypermedia As The Engine Of


Application State) to the full extent intended
by Roy Fielding. The ReST Client Library enables the creation of HATEOAS
applications that are NOT using the URL space,
and it is NOT about doing RPC calls over HTTP using a common exchange format (like
JSON).

The <<library-rest-server>> is a corresponding library for creating usecase-driven


ReST servers, and with that the
corresponding client becomes very thin, as all business rules remain on the server
where they belong.

*The main point is to support exposing REST resources that focus on use cases and
hypermedia.*

On the client, we have been thinking a lot about what Roy wrote in his thesis,
which boils down to "client makes GET
request, based on relation of link invoked and response (headers+hypermedia) make a
decision, and then follow links or
invoke forms to perform state transitions".
It's a state machine.
This is different from your average REST client today in that this model explicitly
says that you need to do a GET
first (otherwise you have nothing to react to), that the "rel" of the link you
followed is important (otherwise context
is unknown), and that the client should not make assumptions about what comes back
(otherwise you cannot deal with
exceptions, on system and application level).

The current REST client approach which is imperative:


[source,java]
--------------
result = client.get(somelink)
--------------
does not allow for any of the above. Instead, the client code should first register
handlers for what to do in various
circumstances, and then simply perform one operation: "refresh". This will trigger
the first GET to the bookmarked URL,
and after that the handlers will do all the work, based on the result. A handler
may continue the work by invoking new
requests, or it may abort. "refresh" does not return any value, and usually does
not throw any exceptions.

Example:
[snippet,java]
-----------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/
client/docsupport/RestPrimerDocs.java
tag=1
-----------

The client first builds up the set of handlers, and describe what they should react
to. The client then invokes
"refresh" which will trigger the first GET on the bookmark URL. This will return a
representation of that context as a
Resource, and the handler for that is invoked. This then invokes the link with
relation "querywithoutvalue" with no
input (no request parameters needed). The result of that is then handled by another
handler, and the invocation of
"refresh" then returns successfully. Note that the first handler may not directly
handle the "result" of
client.query("querywithoutvalue, null) as it cannot be assumed what happens next.
All you know is that you are
following a link.

On crc (ContextResourceClient) it is also possible to registers handlers that are


always applied, such as error
handlers. Here is the setup of crc:

[snippet,java]
-----------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/
client/docsupport/RestPrimerDocs.java
tag=2
-----------

These general handlers cover what to do for login and error handling, for example.
In the traditional REST client this is not as easy to do, as you are more or less
assuming a "happy path" all the time.
In the above scenario there could be any number of steps between doing "refresh"
and getting to the meat of the use
case, such as doing a signup for the website, login, redirects to other servers,
error handling and retries, etc.
It becomes possible to blend general application and error handling logic with use
case specific handlers.

That's basically it. This is where I want to go with support for REST, as a way to
truly leverage the REST ideas and
make it very easy to do REST applications *and* clients based on Polygene, by
keeping the application logic on the server.
In the long run there would also be a JavaScript version of the client, with the
same characteristics, so that you can
easily build a jQuery UI for Polygene™ REST apps.

You might also like