(RESTful) WebService and CleanArchitecture (to what extend doesn't it comply to REST constraints?)

[Andreas Schaefer]

In a scenario where you have the Controllers/Presenters on the client side and the Boundaries at the server side wrapped by an httpWebService, what speaks against having the webService comply to a RESTful architecture?

According to https://en.wikipedia.org/wiki/Representational_state_transfer I'd say although CleanArchitecture can comply with Client-Server, Stateless, Cacheable and Layered System that when it comes to Uniform Interface then it starts to not comply anymore.

The four guiding principles of Uniform Interface are:

 

_Identification of resources_
Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, perhaps, some HTML, XML or JSON that represents some database records expressed, for instance, in Swahili and encoded in UTF-8, depending on the details of the request and the server implementation.

-> OK, you can represent UseCases/Interactors as URIs ... but that's not the way it was meant ;) resources are state/data, UseCases are behaviour/business value that might return data.

_Manipulation of resources through these representations_
When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server should it have permission to do so.

-> I'd say you can't manipulate a UseCase, just execute it. Even if you see the returned data from UseCases as the resource, you then of course can't manipulate it directly.

_Self-descriptive messages_
Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cacheability.

-> OK, this one could work. Although an Interactor would always return (or call the presenter with [e.g. via webSockets]) a plain old data structure that'd get serialized by the webService (in a negotiated format) .. I assume.

_Hypermedia as the engine of application state (A.K.A. HATEOAS)_
Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.

-> This one is interesting. Generally the webService wrapper (which is dynamic by nature) could be seen as a way to provide the decoupling from the Boundaries, as a replacement for the UseCase Factories, Request Builders and Responders (_can it_?).

But how to achieve HATEOAS? Maybe by flexing ...

Code on demand (optional) 

Servers can temporarily extend or customize the functionality of a client by the transfer of executable code. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript. "Code on demand" is the only optional constraint of the REST architecture.

? with which Controllers/Presenters (which hold the information about available Interactors hardcoded) could be delivered dynamically to the client. But it had to be that way for the views as well, doesn't it? .. driving the concept e.g. of (offline enabled) fat client systems (SPAs) ad absurdum.

I don't know if thinking about REST and CleanArchitecture makes any sense to you, but I'd appreciate any of your thoughts on this.

[Roberto Guerra]

I think you are trying too hard. Think of it as two applications: the clients that use your web service, and the server that exposes that web service. Each of those applications need to have their own architecture. If you mix them into one application, then you will tie yourself in knots. 

[Andreas Schaefer]

Roberto,

don't get me wrong. As I tried to imply within the title of the post, I'm thinking that as a matter of the nature of the REST architecture with all it's constraints that it won't make any sense to mix it with a CleanArchitecture. I just wanted to hear your thoughts on this topic :)

Using CleanArchitecture and incorporating the web, I actually can think of either having a thin client and (e.g. MVC) thick server or vice versa where the client uses the web(Service) mostly for persistance. Practically either way there can exist business logic redundancy .. for user convinience or security reasons.

I'd also say that it depends on what your definition of an application is. Of course a webApi can be seen as a complete application implementing a CleanArchitecture where the Controllers/Presenters reside in the webService layer but in that case you'd have to additionally use one of the general, preexisting UIs as the client (e.g. command line or browser) .. and (imho) that (CleanArchitecture) application can't comply to the REST constraints.

Maybe let me put it the other way around: How would you expose a CleanArchitecture application (that's not just simple "data entry" / "forms over data" but incorporates a good amount of value producing business logic) via a webService/webApi (not needing to be RESTful) so that a client can retrieve data in an asynchronous fashion .. and which architecture would you then choose for a web browser client?

[Roberto Guerra]

I'm not sure I understand what you mean by 'architecture ... for a web browser client'.

We normally think of our applications as smaller processes that transform data. This is probably an old and beaten saying, but we try as much as possible to emulate the UNIX philosophy. Small tools that do one thing well and only one thing. We shy away from large monolithic applications as much as possible. So basically, the web services are just end points that can return data or process data for us. The front end clients only deal with presenting that information in whatever way it needs to, without depending on the end point for anything more than the data. The front end still needs business logic, but it is different than what is in the back end. For example, form validation, managing 'routes', sending requests, etc.  We still need to 'architect' these concerns in a 'clean' way. They still need to be test driven. We don't test drive stylesheets and stuff like that. But only the behaviour of the different components on the screen. Even those components are highly modularized. On a single screen, different parts of the screen can be different apps that communicate with each other through an Event Aggregator. For example, there could be a 'Search Form' component that is an app (or sub-app) by itself. A sidebar with filters that is an app, a list of search results that is another app, etc. All of them can be designed independently, unit tested and integrated. I focus mostly on the front end, and from time to time will get my hands dirty with the back end. But when I have to, they are separate applications. Some might be talking to Elasticsearch, some might be dealing with scheduling logic, others might be dealing with more complex process intensive logic. But on the front end, I don't care, I just know that if I need certain data, I have to get it from certain location. I can mock that end point if it is not ready or not available and develop that feature in parallel without having to wait.

In regard to doing things asynchronously, that is not an issue. JS is asynchronous anyway. You can use Promises or FRP to make life easier for you. For example, with FRP you can chain and map over events. It doesn't matter if you are using http requests or web sockets or some other form of communication. Those details should be hidden behind a thin layer. They are 'boundaries' and should be abstracted so you can swap them if you need to.

I hope this was helpful.

[Andreas Schaefer]

Roberto,

yes, it was helpful in understanding your point of view on this. thank you for sharing.

I'm not sure I understand what you mean by 'architecture ... for a web browser client'.

by architecture I mean something like if you do try to follow a specific architectural pattern, like e.g. MV* (that can be achievied with AngularJS framework or Knockout library or others) where you have Controllers on the client side, more importantly if you try to implement CleanArchitecture/EBI with all it's components on the client side as well (as you said, it can be viewed as a whole separate application [ot: hello CleanArchitecture for JavaScript! ;) ]), if mostly you see the client side as a simple "DTO editor" with a deductive UI which would fit REST/CRUD pretty good or if you regard aspects of good UX, not losing user intend, using a inductive UI etc. which would rather fit DDD/CQRS/CleanArchitecture as all of these are not resource oriented but UseCase/Command pattern oriented.

Of course I'm aware of the fact that the decision which architectural pattern to choose may/should be requirements driven. Even CleanArchitecture/EBI might be over the top where a simple "data entry / forms over data" pattern is sufficient (maybe because of the business value that results from it isn't high enough). Think of that: What's the point in using UseCases/Interactors (regarding their imperative nature ..they're Commands!) if you most of the time only had UseCases in the style of: CreateEntityname, UpdateEntityname, DeleteEntityname ... ? Then you'd effectively just have plain old CRUD wrapped in an EBI/CleanArchitecture.

This article (http://cqrs.wordpress.com/documents/task-based-ui/) explain some of my initial thoughts it in much more detail. Regarding (among others) the UI, as in CleanArchitecture UseCases/UserValueToAchieve plays a major role in DDD/CQRS as well, I think the explainations in there apply as good.

After reading the above mentioned article, things like this: (https://blog.42.nl/articles/rest-and-ddd-incompatible/) shouldn't make great sense to you, because in stripping off the behavioural part, you'd then logically wouldn't have UseCases/Interactors anymore .. but this behavioural aspect provides the actual benefit in using CleanArchitecture or DDD.

And thus I'd conclude that CleanArchitecture wrapped by a RESTful WebService doesn't make any sense ... and I asked here in the forum to see, to what extend you think it doesn't make any sense :)

 

We normally think of our applications as smaller processes that transform data ... Small tools that do one thing well and only one thing

OK, now I got you because I know your definition of application. So what I'd call an application I assume you'd rather call a "system" of assembled tools/applications? And your definition of application from my point of view rather applies to my definition of "component" (may it be stand-alone or not).

So basically, the web services are just end points that can return data or process data for us. The front end clients only deal with presenting that information in whatever way it needs to, without depending on the end point for anything more than the data

regarding the fact that I asked specifically regarding a CleanArchitecture (at least at the backend), the architecture you are describing rather applies to simple(r) resource oriented CRUD .. whereas in CleanArchitecture/EBI/DDD the entry points into the application is executable behaviour instead of data/resources and a set of general actions you can execute on it.

I hope this was helpful and that you now know more exactly what I actually meant.

[Sebastian Gozin]

I'm not sure if it's an answer or even on topic so my apologies if it isn't.

I think perhaps you're trying to wrap your head around how REST architectures often want to treat REST messages as resources or collections of data you can manipulate.

So given an architecture which consists of interactors which can be invoked with an input boundary and receives output boundaries as a ui plugin would typically do. And these interactors would in turn use gateway boundaries to fetch and operate on entities hydrated with a persistence plugin.
Then I tried to do the following once:

client side:
AngularJS > Interactors.js > Gateways.js + REST client

server side:
Grails > Interactors > Gateways + GORM

Where of course the Javascript REST client would invoke Grails REST services.

This pretty much failed for me because interactors on both sides had to communicate things like input validation errors up the stack. Which in this case would have to pass through the gateway boundary on the client side. And I never felt like this was a good fit. I felt like the gateway boundary suddenly had to deal with concepts it had no business with.
So I changed it up a bit to this:

client side:
AngularJS > Interactors.js + REST client

At some point I reasoned that REST is simply my transport protocol and I wasn't interested in sending persistence related messages but usecase related messages. Given I at first crossed a boundary which put me in a different context the messages I was getting from the server didn't make any sense for that context. I think this may not be very RESTy.

In retrospect I could instead have eliminated the interactors on the server side to allow more RESTful usage patterns but I don't see me do that easily.

[Andreas Schaefer]

Sebastian, thank you for sharing your experiences! I do appreciate that!

On Thursday, January 23, 2014 10:34:34 AM UTC+1, Sebastian Gozin wrote:

I'm not sure if it's an answer or even on topic so my apologies if it isn't.

It is :)

 

I think perhaps you're trying to wrap your head around how REST architectures often want to treat REST messages as resources or collections of data you can manipulate.

That actually is very clear to me. Like it is described e.g. on the above mentioned wikipedia page for ReST, it should become clear that architectures that do not for the most part treat messages as resources simply don't comply to the mentioned REST constraints and thus aren't RESTful. In particular most Services/Systems won't actually comply to the 'Uniform Interface' constraint, as (like I initially described in my first post) "Manipulation of resources through DTOs that were sentby the server" won't fit to a behavioural, UseCase oriented architecture where you send Commands to the Service instead of resources.

It rather fits the resource oriented 'Stereotypical Architecture' that is very good explained here: http://cqrs.wordpress.com (which is a must-read anyway).

 

So given an architecture which consists of interactors which can be invoked with an input boundary and receives output boundaries as a ui plugin would typically do. And these interactors would in turn use gateway boundaries to fetch and operate on entities hydrated with a persistence plugin.
Then I tried to do the following once:

client side:
AngularJS > Interactors.js > Gateways.js + REST client

If in this scenario you add a simple resource oriented, CRUD WebService (not REST because e.g. HATEOAS wouldn't make any sense here) that has potentially no businessLogic but only implements persistence .. that'd actually be a good fit. If this would be a good pattern for public facing websites may be discussed because practically every authorized user may fiddle data into the "db" directly bypassing any client businessLogic. As a side note: in this scenario an alternative to a webService might me something like pouchdb (http://pouchdb.com/).

 

server side:
Grails > Interactors > Gateways + GORM

Where of course the Javascript REST client would invoke Grails REST services.

This pretty much failed for me because interactors on both sides had to communicate things like input validation errors up the stack.

Thanks for sharing this experience. I slightly touched on this topic in this thread here: https://groups.google.com/forum/?hl=en#!topic/clean-code-discussion/nWiKeVAy6ec

 

Which in this case would have to pass through the gateway boundary on the client side. And I never felt like this was a good fit. I felt like the gateway boundary suddenly had to deal with concepts it had no business with.

You could have let the error messages just bubble up the stack!? But of course overall this is kinda misfit. Each layer of the stack where you have to interpret/handle errors makes the architecture more complicated.

Technical errors regarding data retrieval/persistence on the other hand must suley be considered at this point but that's whole different error category.

 

So I changed it up a bit to this:

client side:
AngularJS > Interactors.js + REST client

At some point I reasoned that REST is simply my transport protocol and I wasn't interested in sending persistence related messages but usecase related messages.

And as REST is no technical detail but rather an architectural and semantic pattern at this point it can't be seen as RESTful anymore but just a more general http webService ... which of course may not be seen as a drawback. It all depends on what you're trying to achvieve and with which constraints you wan't to comply :)

Then furthermore at this point I'd ask myself what's the point in still having Interacors on the client? Controllers/Presenters might be sufficient (of course in addition you can flex Angular services to extract the technical boiler plate code responsible for the communicaton with the webService)

Maybe at this point an inductive task-based-UI may come in handy as opposed to implementing a deductive one (http://cqrs.wordpress.com/documents/task-based-ui/) because imho this much better fits the Command pattern of the Interactors/UseCases.

 

Given I at first crossed a boundary which put me in a different context the messages I was getting from the server didn't make any sense for that context. I think this may not be very RESTy.

right. It even wasn't RESTy before as mentioned above ;)

 

In retrospect I could instead have eliminated the interactors on the server side to allow more RESTful usage patterns but I don't see me do that easily.

Why not? I'd be interested in what makes you think it'd be hard. I can imagine like i mentioned above that could be for security reasons I guess? .. Same here, take a look at pouchdb ! ;)

 

[Sebastian Gozin]

Great, indeed it wasn't RESTful.

It rather fits the resource oriented 'Stereotypical Architecture' that is very good explained here: http://cqrs.wordpress.com (which is a must-read anyway).

 

I should read that soon...

Why not? I'd be interested in what makes you think it'd be hard. I can imagine like i mentioned above that could be for security reasons I guess? .. Same here, take a look at pouchdb ! ;

I don't think it would be hard. I think it would push business logic to the client while I want the server to retain final authority. Thus the server must know about the usecases and must have a way to communicate contextual issues which are larger than the scope of a single resource.
At least with my current understanding I feel stuck going down that road.

However if I let go of my desire to have the server control everything then I think I'd have no immediate issue with it and something like pouchdb would be an option.
It might even be fun as I'd be able to write more of the app in javascript.

[Andreas Schaefer]

On Thursday, January 23, 2014 3:22:54 PM UTC+1, Sebastian Gozin wrote:

Why not? I'd be interested in what makes you think it'd be hard. I can imagine like i mentioned above that could be for security reasons I guess? .. Same here, take a look at pouchdb ! ;

I don't think it would be hard. I think it would push business logic to the client while I want the server to retain final authority. Thus the server must know about the usecases and must have a way to communicate contextual issues which are larger than the scope of a single resource.
At least with my current understanding I feel stuck going down that road.

It all depends what you're trying to achieve, what the requirements are, in which context the app is supposed to be used (public or private).

Having the businessLogic in only one place or having it in several places .. each scenario has it's benefits and tradeoffs.

 

However if I let go of my desire to have the server control everything then I think I'd have no immediate issue with it and something like pouchdb would be an option.
It might even be fun as I'd be able to write more of the app in javascript.

fun and a plethora of different platforms your app can run on :)

Or you just split it up, like ...

when the client must also be browser based then for security reasons have duplicate businessLogic on the server side.

If you just want't to have your app on different native platforms (e.g. with phonegap build, icenium etc.) where you have more control over the client side then leave businessLogic out on the server side and share your client side businessLogic code base among the different apps as good as possible!

[Sebastian Gozin]

I agree it all depends on the requirements of what we are building.

So in the context of the OP I think CleanArchitecture suggests end-user application while RESTful suggests well... database to me.
That seems to be exactly what CouchDB and PouchDB do. In their context it is a good fit.

When we build an end-user app on top of that I suppose we'd quickly introduce things which go outside of the constraints of REST. Or we just distribute the application logic.

[Roberto Guerra]

I don't think it is web-service(or REST or SOAP or RPC or whatever) OR local storage (not in reference to HTML5 local storage). If you want a good mobile client you have to use both not one or the other. The part that deals with the remote calls and persistence are the slimy messy stinky part that you wrap in something and put in the boundary. Your client shouldn't know about it and should only talk to it through an interface. The logic that deals with persistence then has to deal with knowing  when the app is offline so it stores locally, when the local data is stale so it synchronizes etc. It is sort of the persistence layer of the rich clients. The way we used to build apps in the server side doesn't make sense in the client, so we can't be conflating the terms. There will be things in the client side that have no equivalent in the server side and vice versa. However, we can still apply good fundamental practices to the client side.

[Uncle Bob]

REST is an interface strategy, not a system architecture.  It is a specification for initiating use cases, not a specification for organizing internal structure.  

All applications, RESTFUL or not, have use cases.  A use case is simply an operation upon the state of the system, given some input data, and providing some output data.  A RESTful interface is simply a naming scheme for those use cases; one that proliferates and articulates nouns while drastically constraining verbs.  The noun-verb combination identifies a use case, and the rest of the message supplies the data.

In a server with a RESTful interface the controllers identify the resource (the noun), interpret the verb (GET, POST, etc), and then select the appropriate interactor.  Everything else follows as usual.  

[Dave Schinkel]

UB when you say "In a server with a RESTful interface the controllers identify the resource"...

What do you mean by the controllers identify the resource.  What does identify mean as in implementation.

Your reply helped me as well.  I'm building out a REST API that's really a Data API that should be resuable (generic enough) to other clients hopefully but that means I think we should put a gateway API above all this...

Right now I have routes coming into the web service, mapping to controllers.  But I didn't realize controllers should be then mapping to interactors and then interactors will manipulate/use Entity business logic.  It's the controller piece I want to make sure we're doing right here.  What would the interactors look like and do in this case once the controllers map to the right interactor?  I assume after watching your Episode 7 cleancode video that the interactors would process the request and create the simple POCO data objects to be then passed to the Entiy objects still...

So basically Controllers shouldn't be calling any Entities, they should only be talking to interactors right?  And would I inject interactors into my controller in that case so that I could also mock interactors in the case where I want to test my controllers?

[Dave Schinkel]

And thus if I am I correct UB above, then controllers become the "boundary" objects in a REST API?

[Dave Schinkel]

"REST is an interface strategy, not a system architecture.  It is a specification for initiating use cases, not a specification for organizing internal structure.  "

but the fact that REST interfaces are coupled to use cases in that the incoming params of a request are part of the use case, doesn't that then drive some of you architecture below the interface to a great degree?

On Sunday, January 26, 2014 at 1:20:51 PM UTC-6, Uncle Bob wrote:

[Norbert Nemes]

I don't think it does.
The controller parses the request for the relevant parameters and passes them to a use case factory, that returns a use case.
Controller executes use case and has the response data formatted (JSON or whatever).
Controller returns formatted data.
As such, the controller knows nothing about what the use case does, and there's no coupling.

[Dave Schinkel]

Thanks much UB.

So in my situation, let me see if I can boil this down and see if I get this...being the grey line for me is the boundary at this point that I wanna clarify.

I'm using Koa.js which is similar to Ruby's Rack Connect.  By that I mean that I've got a .js file which contains koa verb based javascript methods (.get(), .post(), etc.) which receive the incoming http request.  

I will be using koa-controller to map the http request to a controller (node.js module) to process the request.

Lets look at some code.

This is a koa endpiont interface method which handles a GET call for the route "/search"

        router.get('/search', '/search', function *(next){

            this.body = "search route hit";

            this.statusCode = 200;

        });

So UB, am I correct to assume that the boundary here the koa router's get() method here (which is really the interface to the deliver mechanism...because it's here where it intercepts the raw http request).

If I'm right about that, then am I also correct about saying that in terms of implementation details, get() method is responsible as only a pass-through in that it only sends the raw request object to a controller.  I wouldn't be doing any validation here, just mapping the request to the controller right?

And then in the controller is where any parameter validation happens and the de-packaging of the raw http request into a new request Model DTO (agnostic of any delivery mechanism) that requestModel is to then be passed to interactor objects...right?

On Sunday, January 26, 2014 at 1:20:51 PM UTC-6, Uncle Bob wrote:

[Sebastian Gozin]

I think 'controller' for most people would be the function you passed to the router.get method.
I would do the HTTP unpacking (not validation) in there.

The interactor is what I believe UB thinks is the true controller but because of web-MVC he chose another name to avoid confusion.
I'd expect validation to happen in the interactor.

[Dave Schinkel]

Sebastian, so are you saying the controller is really the "boundary" in this scenario?

[Dave Schinkel]

"I'd expect validation to happen in the interactor."

I assume you're speaking to parameter validation from an http request....right?  Just so I know we're on the same page here...

On Monday, August 24, 2015 at 4:33:57 AM UTC-5, Sebastian Gozin wrote:

[Sebastian Gozin]

Sebastian, so are you saying the controller is really the "boundary" in this scenario?

From the Grails documentation which uses Spring Web MVC.
You can map a url pattern to a controller by adding the following line to UrlMappings.groovy

"/search"(controller: "search", action: "list")

You can then implement some logic to happen when /product is called by implementing the file grails-app/controllers/myapp/SearchController.groovy

class SearchController {
  def list() {
    render status:200, text:'search route hit'
  }
}

If I compare this to your example code from koa then I think you'll agree I have not done anything more than you did.
But Grails (and other frameworks) made me implement a "controller". Which is why I was saying your function passed to router.get is your WebMVC controller.

router.get('/search', '/search', function *(next){

           this.body = "search route hit";

           this.statusCode = 200;

       });

I bring this up because I see no reason to introduce another controller in between the function you passed to router.get or my own SearchController and the interactor.
Especially if you're going to pass HTTP related artifacts to this controller which would then create the true transport agnostic request object.

I would simply implement my SearchController as follows to:
- convert the HTTP params and request locale into a search request object (simple hash table)
- convert the search results into JSON
- convert input constraint violations into JSON and setting the HTTP response status to indicate invalid input was received.

class SearchController {
  def searchInteractor

  def list() {
    searchInteractor(searchRequest, this)
  }

  def getSearchRequest() {
    [q:params.q, locale:request.locale]
  }

  def ok(results) {
    render(results as JSON)
  }

  def rejected(violations) {
    response.status = 412
    render(violations as JSON)
  }
}

At this point I can implement the searchInteractor function without HTTP.
I guess I'm saying the searchInteractor+searchRequest+searchResult+searchViolations are the boundary.
The SearchController is simply an HTTP/REST transport.

[Dave Schinkel]

Thanks Sebastian, this helped a lot.

One thing I don't see is how the Interactor would be part of the boundary.  Isn't the interactor after the boundary?  I was watching UB's video on this and his diagram shows the interactor on the right side of the boundary, not part of the boundary.

So there's actually a koa-controller middleware.  Same idea as your search controller.

I am curious to also see people's Interactor objects and what they're injecting into them and how they're performing and structuring those objects.

[Dave Schinkel]

This makes me wonder about another topic, validation.

The controllers would be validating the incoming http request params and body data for stuff like length, and other param validations.

I would think that controllers would also then be use-case specific as each controller could technically have different logic depending on the use case, even for simple param validation.  OR maybe I'm looking at this wrong, that Controller validation on request params should be uniform.  That is, if One controller for an update action requires carId and another controller for a different endpoint requires carId, can we assume the same validation for carId in the incoming request is always going to sue the same validations, such as carId must be an integer, carId must be > 0, etc.?

so if you're creating a REST API that is to be consumed by many applications in the future, do you treat the param validation uniformly across all endpoints for the same input params?  I think the controllers should be app independent on param validation and so validation on fields used across controllers should use the same validation for a specific param being validated for example.

[Sebastian Gozin]

Are you talking about this image?
http://i.stack.imgur.com/UpCvB.png

If so I meant not the interactor itself but the interface it implements, the arguments it receives and it's return value.

In my example the boundary could've been something like:

function(SearchRequest, SearchResponseHandler);

class SearchRequest {
  String q
  Locale locale
}

interface SearchResponseHandler {
  void ok(results)
  void rejected(violations)
}

[Dave Schinkel]

yes that image.

I wonder though after injecting persistence (repository) into the interactor an example of how it'd use it.  And again I view the word "Entity" as a business object with application independent business rules.  Interactors use the Entities to help fulfill the implementation of the use case.  I wish I could see a decent interactor in code, one that's real world...not just the simple ones you see out there.  I'm going to have to be coding some interactors soon, actually this week so once I get our pattern down well, I'll post examples on Git

[Dave Schinkel]

Another thing that is a bit vague.

Entity and Entity Gateway and Entity Gateway Implementation.  

It's obvious that Entity is a Business Object with business logic

Entity Gateway - what is this?  Is this a Repository Object (Yes I know the concept of Gateway and Repository are similar but I'm using Repository for the sake of context in my discussion but I know 8th Light likes to name similar layers using Fowler's "Gateway" pattern)

Entity Gateway Implementation - I'm assuming this would be the translation layer, the guts of your repository - its logic that takes a Data Model and converts it into a business data model to be passed back upstream

[Sebastian Gozin]

I currently consider the entity gateway and entity repository as the same thing.
If someone can offer a good explanation as to why they are not I'm happy to stop confusing the world ^^

I seem to agree with your interpretations here.
I'd maybe suggest a naming strategy I got from one of our fellow cleancode forum friends.

Rather than call something a BookGateway or BookRepository you could call this abstraction a Library.
I thought that was a really cool idea.

[Dave Schinkel]

Yea I've used gateway too.

So the difference to me is that Repositories normally only work with a data store.

A gateway can work as a facade for many different things (returning entities, calling third party services, hitting a database).  So to me it's got a broader use case.  Sure you could just use a gateway to return data from CRUDs.  But that's where personally I distinguish the two, the scope of what the facade is.

[Dave Schinkel]

Check out my clean architecture sketches and let me know what you think.  This is related to the poster's question, I went through the same headaches and this is what I came up with.

https://drive.google.com/folderview?id=0B6FDE5kMwYTlfjJDWDZIZktwNVNvR3JEUmdxcnFYbUJHa2NGLWMyTUU2TFZGZmlZU1BmNFk&usp=sharing

[Dave Schinkel]

Another way to call it also Sebastian I think would be a "Facade".  Example:  DALFacade

[Sebastian Gozin]

Yes, I think you're right about that.

[Rusi Filipov]

I see the HTTP/REST related elements as elements on the outer side of the application boundary and treat them just like any other UI. I would implement the core application in one component (jar/dll) and the REST in another component, which depends on the application core, but not the other way around.

In the simplest case, the application core defines 2 interfaces: CommandHandler and EventHandler. The CommandHandler is implemented by the interactor and used in each REST entry point. The EventHandler is implemented in another class within the REST component and used by the interactor. The implementation of the EventHandler might be a HTTP client itself, which pushes the events to another service (if you are integrating two services). Or it might be pushing the events via web sockets or something similar if your client lives within the browser.