BETA - Published for Community Feedback. This page is a wiki.  Please provide your feedback in the comments below.

Two-Tier Service Application Scenario (REST)

J.D. Meier, Alex Homer, David Hill, Jason Taylor, Prashant Bansode, Lonnie Wall, Rob Boucher Jr, Akshay Bogawat

Applies To

  • Microsoft .NET, 3.5 SP1 and above
  • Windows Server 2003, 2008

Scenario

In this scenario, you have full control over the creation and management of the database schema. In addition, the service application will be deployed and accessed from within a local area network, which means that the web server does not need to be deployed to an isolated perimeter network. As a result, this scenario can be implemented using a two-tier design with the web server representing one tier, and a database server representing the second tier.

Scenario.PNG

Key Characteristics

  • Web service implemented using REpresentational State Transfer (REST).
  • Service and business logic are located on the same physical machine.
  • Client interaction with the service uses standard HTTP GET, POST, PUT, and DELETE commands.
  • The service layer uses a message-based protocol to interact with the business layer.
  • The business layer uses data entities that represent objects in the domain.
  • The application has full autonomy over the database schema.

Pattern Solution

The following diagram displays the major patterns used by this scenario and the layers where those patterns are implemented.

PatternSolution.PNG

The following is a summary of the patterns used by this scenario:
  • The service layer uses a Router pattern to map Uniform Resource Identifiers (URI) to business logic.
  • The REST Entity pattern is used to define resources exposed by the service.
  • An Entity Translator pattern is used to translate between REST entities and Domain entities.
  • The business layer uses a Façade pattern to implement a message-based interface between the service and business layer.
  • Transaction Script objects are used to handle business request processing.
  • A Repository pattern is used to access domain entities.
  • A Domain Entity pattern is used to define business entities that contain data only.
  • A Data Mapper pattern is used to map domain entities to the database schema.

Pattern Description
Behavior (REST) Applies to resources that carry out operations. These resources have generally no state of their own and only support the POST operation.
Data Mapper Implement a mapping layer between objects and the database structure in order to move data from one structure to another while keeping them independent.
Dependency Inversion Use a base class or interface to define a shared abstraction that can be used by multiple layers in the design. The principal behind dependency inversion is that high level components should not be dependent on low level components. Instead, both should depend on an external abstraction.
Domain Entity A set of objects modeled after a domain that represents the relationship between entities in the domain but do not contain behavior or rules related to the entities. In other words, this is a data entity that represents an object from the domain.
Router Route requests to specific business components or business logic based on pre-defined criteria.
Entity (REST) Resources that can be read with a GET operation, but can only be changed by PUT and DELETE operations.
Entity Translator Implement an object that transforms message data types to business types for requests and reverses the transformation for responses.
Façade Implement a unified interface to a set of operations to reduce coupling between systems.
Repository An in-memory representation of a data source that works with domain entities.
Store (REST) Allows entries to be created and updated with PUT.
Transaction (REST) Resources that support transactional operations.
Transaction Script Encapsulate operations that occur as part of a transaction into a single operation that executes the individual operations one at a time.

Pattern Solution Details

The pattern solution identifies primary patterns used by this scenario. The solution summary provides information on how the patterns are used within the design. Each table below represents a logical layer in the design and contains the patterns associated with that layer.

In this solution you will:
  • Use a router to map REST URIs to handlers that manage the associated resource.
  • Use an entity translator to convert between REST entities and domain entities.
  • Use a message-based protocol for communication between the service and business layers.
  • Implement a Domain Entity pattern to represent business entities.
  • Interact with the database using Repository and Data Mapper patterns.
Web Server – Service Layer
Service layer components provide access to business logic in the application. Service consumers interact with the service layer by passing messages to and from it over a communication channel.

Pattern Info Example
Router
Used to route requests sent from a consumer to a specific operation. Requests being handled by IIS are intercepted and sent to a handler that will process the request.
Uses static information to define the criteria used to route requests. In this scenario a route table is initialized that provides a mapping between REST URIs and components that handle the request.
Entity (REST)
Represents a resource that can be retrieved using GET and can only be updated using PUT and DELETE In REST a resource is an object that represents a specific state. You can change that state by performing operations on the resource. In this scenario business entities are translated into REST entities, or resources, that support GET, PUT, and DELETE operations.
Entity Translator
Used to translate between business entities and REST entities exposed by the service. Resources exposed by the service represent an external contract while business entities are internal to the service. As a result, translators are required to move data from one format to another.
Web Server – Business Layer
Business layer components implement the core functionality of the system, and encapsulate the relevant business logic. In this scenario a façade pattern is used to support a message-based, or coarse-grained, interface into the business layer.

Pattern Info Example
Facade
Provides a coarse grained interface into the business layer. Rather than defining chatty object based operations a façade combines multiple operations into a single interface.
The service implementation interacts with the business tier through the façade. The service implementation is responsible for translating between external contracts and internal entities and then passing the request on to the business layer façade.
An interface type is used to define the façade interface. In order to provide a common interface, a typical approach is to define the façade using an Interface type with a single operation used to handle all requests.
Transaction Script
The façade uses transaction script objects to execute business operations. Within the façade an appropriate transaction script object is initialized based on the operation being executed, and control is passed on to a transaction script operation.
Supports business operations that need to be executed as a single unit. Within the transaction script operation a transaction is started, one or more business operations are performed, and the transaction is committed or rolled-back based on the outcome of the business operations.
Provides a single point of entry for requests. This allows you to execute multiple business and data access operations from a single function called by the facade.
Web Server – Data Access Layer
Data layer components provide access to data that is hosted within the boundaries of the system, and data exposed by other back-end systems.

Pattern Info Example
Repository
A repository provides an in-memory representation of domain entities. As a general rule objects are normally not stored in memory with a web application or service. However, the repository hides all database interaction and provides operations that manipulate domain entities as if they were in memory.
Criteria objects can be used by the repository to generate database queries. In cases where you have multiple complex queries to retrieve an entity, a criteria object can be used to define selection criteria that is passed into a single get operation.
Data Mapper
Impedance mismatch between objects and relational data require mapping layer There are several factors that cause a mismatch between object and relational database structures. As a result, a mapping layer can be used to map object structures to database schemas. This allows developers to perform operations against the objects without having to know the database schema.
Domain Entity
Business entities are defined that represent entities within the application domain. In this scenario you have full control of the database schema and can define business entities based on entities in the domain and the relationships those entities have with each other.

Technical Solution

The following diagram represents the technical solution by replacing patterns shown in the Pattern Solution with technologies, interfaces, or objects that are used to implement the pattern.

TechnicalSolution.PNG

The following is a summary of the technologies, interfaces or objects shown above:
  • The ASP.NET Routing infrastructure is used to implement the Router pattern.
  • REST entities are defined as resource objects.
  • Translator objects are used to convert between resource objects and business entities.
  • A common message-based interface is defined for the façade into the business layer.
  • Business process objects are used to implement the transaction script pattern.
  • Repository objects are used to provide a data access interface.
  • Business entities are defined using the ADO.NET Entity Framework’s Entity Data Model (EDM).
  • The ADO.NET Entity Framework is responsible for mapping business entities to the database schema.
  • The database used by this application scenario is SQL Server.

Technical Solution Details

The technical solution provides information about technologies used to implement patterns that were identified in the pattern solution. Each table below represents a logical layer within the design and provides information and examples related to implementing patterns in the solution. In addition to the technical solution for patterns, these tables also provide technical considerations that should be checked for this scenario.

In this solution you will:
  • Use the ASP.NET Routing infrastructure included in Microsoft .NET 3.5.
  • Host the service application using Microsoft Internet Information Services (IIS)
  • Implement a message-based interface for interaction between the presentation and business layers.
  • Use the ADO.NET Entity Framework to define business entities and map those entities to the database.
  • Access tables, views, or stored procedures from a SQL Server database.
Web Server – Service Layer
This scenario takes advantage of the routing infrastructure in Microsoft .NET to map resource handlers to URIs instead of web pages. When a REST request is received by IIS it will be directed to a specific HTTP handler associated with the URI, which represents a REST resource. The HTTP handlers are responsible for interacting with the business layer, initializing the appropriate REST entities, which are considered resource objects, and performing translations between REST entities and business entities.

Check & More Info Example
ASP.NET Routing
Use the routing infrastructure that is included in Microsoft .NET 3.5 SP1 Add a reference to System.Web.Routing
Add an httpModules entry to web.config that will configure a URI routing module that will intercept HTTP requests. URIRouting.PNG
Define route handlers that implement the IRouteHandler interface and return HTTP handlers that are used to perform operations on REST resources. RouteHandler.PNG
Register the URI route handlers in Global.asax by adding them to a static RouteTable that is defined in the .NET routing infrastructure. GlobalHandler.PNG
Resource Objects
Classes are defined that represent REST entities, or resources, that are exposed by the service. Define classes representing entities exposed by your service that can be serialized into XML, or other MIME types as necessary, for transmission using HTTP.
Use embedded URIs in the resource to reference other resources associated with the current resource. Similar to a web application where an overview page may contain links to detail pages, a REST resource can provide URIs that link to other resources, which represent details associated with the current resource.
Translator Objects
Classes are defined that provide operations to translate between business entities and REST entities. TranslatorObject.PNG
Web Server – Business Layer
This scenario uses a message based façade design to provide an interface into the business layer from the service layer. The façade can be defined as a shared abstraction that uses a common class defined as a Message that acts as a container for data being sent to and returned from the business layer. The façade passes control to business process objects that know how to process the request and can manage transactions if necessary. Business process objects are responsible for interacting with the data access layer through repository objects.

Check & More Info Example
Façade Interface
The business layer implements a façade with coarse grained operations. Define a generic operation that takes the command and message container as parameters and returns the message container.
An Interface type is used to define the façade interface. InterfaceFacade.PNG
The Façade acts as a boundary that catches all unhandled exceptions that may occur when processing business operations. BuisnessFacade.PNG
Business Process Objects
You are using business process objects to handle requests made to the business layer. Business process objects allow you to implement business rules and provide transaction support if required.
Business operations that need to be included in a transaction are combined in a single operation exposed by a business process object that implements the transaction script pattern. Promote.PNG
Business process objects can also be used to initialize a common Entity Framework data context that is used by repository objects when interacting with the data access layer. This approach allows you to maintain context with one object while processing the request. This will ensure that all updates to business entities are saved when the context is saved. There are several ways to manage the data context; you can use either the CallContext or HttpContext to hold an instance of the data context, or you can initialize the data context and pass it to repository operations. IMPORTANT! You must dispose the data context object before returning control back to the façade.
Web Server – Data Access Layer
The primary interface into the data access layer is through repository objects, which provide an illusion that business entities are being maintained in memory. For example, business process objects can perform get, save, and update operations on business entities without having any knowledge of the underlying data store used to persist the objects.

Check & More Info Example
Data Access Objects
Identify parent objects in your entity data model and define a separate repository object for each one. Parent objects represent the top level object in a in a group of objects that are related. If you have a one-to-one mapping between objects and tables or views in the database you will normally create a repository object for each table or view object.
Define operations that use Entity Framework data entities, or business entities, as parameters and return values. AccountRepository.PNG
For objects that can be retrieved using multiple complex queries consider using a criteria object to define the queries instead of defining a separate operation for each query. A typical approach is to define a common criteria interface that all criteria objects implement. CriteriaInterface.PNG
Business Entities
Use entities from the Conceptual Model of the ADO.NET Entity Framework’s Entity Data Model to represent business entities. Business entities are defined as part of the Entity Data Model (EDM) used by the ADP.NET Entity Framework. When first creating an EDM the recommended procedure is to use the EDM Wizard. You can also use EdmGen.exe to generate an EDM from an existing database schema, or you can create the model manually. The ADP.NET Entity Framework also provides an EDM visual designer that you can use to manage the EDM.
Consider using domain modeling to define the entity data model. Before creating the Entity Data Model (EDM) you should first analyze the business domain in order to identify domain entities and the relationship between those entities.
Business rules are not implemented within the business entities. With this design the business entities are just data containers. Business rules are handled by business processing components.
ADO.NET Entity Framework
The ADO.NET Entity Framework is responsible for managing the database schema and providing a mapping layer between the database and data entities. In this scenario a database schema does not exist and we can take advantage of the schema generation and management functionality provided by the ADO.NET Entity Framework. This is accomplished by using the Entity Data Model (EDM) visual designer to create the EDM.
The Entity Data Model provides a mapping layer between the conceptual model and storage model. The Entity Data Model (EDM) is actually composed of three separate language types. The store schema definition language (SSDL) is used to define the storage, or database, schema. The conceptual storage definition language (CSDL) is used to define the entity types, complex types, associations, entity containers, entity sets, and association sets in the application domain. Finally, the mapping specification language (MSL) is used to describe the mapping between the conceptual model and target database.
Database Server
Check & More Info Example
Trusted sub-system is used to access the database. Define a common business identity and then use that identity when accessing tables and views in the database.

Additional Resources

Last edited Jan 24, 2009 at 1:09 AM by rboucher, version 4

Comments

rboucher Jan 29, 2009 at 8:05 PM 
Update. We are talking with Seb, Colin, and Greg Young on this and wil make updates.

rboucher Jan 27, 2009 at 5:11 AM 
Thanks Serialseb. We are taking a look at your post. We appreciate the time you have put into this. Just as a note, this article was just posted a week or two ago to start the feedback loop. Where are you getting that it's a BETA2? Did we mess up and put that somewhere?

riles01 Jan 25, 2009 at 11:38 PM 
serialseb's post is a much more clearly stated version of the comment I wrote and then lost. Excellent points, serialseb.

serialseb Jan 25, 2009 at 5:15 PM 
I've published a detailed analysis. See http://serialseb.blogspot.com/2009/01/how-to-fix-microsofts-two-tier-service.html

colinjack Jan 23, 2009 at 6:17 PM 
One other point. I'd be interested to know why you guys think this is a good design? You don't really explain why you're doing this. I think its important to remember that patterns are more than some characteristics, a solution and then a technical solution...at the minimum if we're going GOF style we need applicability.

Also lets look at an alternative design where we approach things more like ASP.NET MVC has:

1. I route directly to an action - EmployeesRouteHandler is gone.
2. We use convention based binding with option to override with model binders as appropriate, binding directly to a class that I think you consider the resource entity - No need for all that messy binding code.
3. My action is running on the Web server so it loads up a behavioral (and object oriented) domain. So I might load a Customer domain object then delete it using the repository, or I might call a method on it and let it take care of some calculation - No need for the facade or business process objects.

We've gone from a very complicated architecture to one that is simple, object-oriented and maintainable. In step 2 you could use some of the data contract serialization classes that ship with WCF maybe, to serialize to/from XML, but its irrelevant how you do it the key point is we have a seperation between different concerns (routing, resource structures, domain model, persistence) and we've got a clean design to build upon.

colinjack Jan 23, 2009 at 3:54 PM 
@Darrel
Very good point. And its a pity associating contracts to media types and adding links in to representations isn't easier in RESTful WCF either...

DarrelMiller Jan 23, 2009 at 2:57 PM 
Like Colin, I also am having a hard time with this notion of a REST entity. Can you explain how a REST entity relates to a Media Type?
What I fear people will interpret by reading these guidelines is that if they are modeling an Employee domain entity, they should create an Employee REST Entity, and repeat ad infinitum for all domain entities. What I think you're suggesting is that the employee REST entity would then be transferred to the client as application/xml, application/json or some other generic data format. "application/xml" is fine as long as the client just renders xml attributes and entities. However, I suspect many clients will try and dig into that xml to get employee information. This introduces coupling that the REST architecture is trying to avoid. The benefits of media types such as Atom is the specification of standard elements such as <feed> and <entry> so that the client has some semantic understanding of the representation being retrieved.
People building RESTful applications need to understand that the idea of having a constrained set of media types to limit the client/server coupling. Embedding employee entities inside application/xml is just as subversive as tunneling verbs through POST.
If you really believe that people need to expose "employee REST entities" then they should be creating a application/vnd.mycompany.employee+xml media type. i.e. a new media type for each REST entity.

colinjack Jan 23, 2009 at 2:37 PM 
Ta for replying, good to get a dialogue going around this stuff.

> The main thing to understand is that we are not using a domain driven design in this pattern.
> Instead, this uses a domain entity pattern where you model business entities after a domain but do
> not include business rules in the entities. In other words, these are not business objects but
> rather data containers modeled after a domain, which is consistent with the Entity Data Model in
> the .NET Entity Framework. REST resources are defined in the service layer and translators are used
> to convert between domain entities and REST resources (Entities). In other words, only the contract
> (resource) is exposed and the implementation (domain entity) is never shared.

Problem with that is you are using domain model and REST terminology but not the underlying ideas. If you have no behavior just call it a data model or a DTO, calling it a "domain entity" whilst also referring to domain model patterns like repository is just asking for confusion.

On terminology the way you write it here makes more sense, we have REST resources. Calling things Resource objects or REST entities is just asking for confusion.


> This would be true in a domain driven design; however, as mentioned this is not a domain driven
> design.

I'm referring to Fowler PoEAA not DDD here. He describes these patterns the way I've shown and that will be the source of most peoples understanding of the patterns. Transaction script is an alternative to a domain model and repositories are for use when you have a domain model. Why not just stick to the terminology in the second (perhaps older) diagram with "business entities" and "data access objects".


> REST Entities are externally exposed and defined in the service layer similar to data contracts in
> SOAP.
>
> The translators initialize REST resource objects with domain entities, and the resource objects are >converted into XML for transmission over the wire.

Hrm, I'm sill confused.

On the REST entities we're talking of the classes that handle the data contracts which is fine. So if we were using WCF it'd be the DataContract. Would it be worth clarifying this by describing them how you'd associate them with media types?

Still not clear on the whole REST resource object idea, is it just another name for the same thing?


> While I tend to agree WRT the overloading of Entity there really isn't a better term for what these
> objects represent. In addition, Entity is actuallly farily common in relation to different REST impelementations.

I'd stick to talking about resources and handlers, or ask in rest-discuss or another common forum where you can get expert REST advice.


> Google REST Entity and you'll see different examples, including the Blob REST entity in SQL Data
> Services.

Just Googled it, started off without quotes and top link is for EF and REST, 2nd one is App Arch Guide home page, 3rd one is not referring to rest entities, 4th one is Microsoft advice again.

More tellingly google "REST entity", with the quotes, and you get no meaningful


> However, I would have to disagree with the first part. URI's are a major component of REST. The way
> to think about REST is to think about how you navigate through a web site.

Sorry I didn't explain in detail. I mean that addressable resources are important, it doesn't need to be a URI (though with REST+HTTP it obviously is). Compared to some of my other points this was a bit picky and I shouldn't have made it.


> I agree that the termonology could be better here.... and am open to suggestions. The idea is that
> REST entities represent a definition or class while resource objects represent the instantiation of > the class. However, I can see how mixing terms like
> this can be confusing.

So just to check I understand correctly. You've got your representations (XML/JSON) and you've got your resources and in the middle you've got the classes that represent this data contract (in WCF the DataContract). We're describing those classes that sit in the middle.

Personally I'd reach out to known RESTians in the .NET space including Alan Dean (http://alandean.blogspot.com/) and Sebastien Lambla (http://serialseb.blogspot.com/2009/01/openrasta-status-update.html).


> Another thing to keep in mind with this App pattern is that the design used here may seem like
> overkill... but it promotes strict separation of concerns with a layered approach that can scale
> out to handle a large number of resources. I've used a similar pattern for web applications that
> started out around 50 pages or so and have scaled out to several hundered pages over several years
> without having to change anything in the design.

I get what your saying but I'd embrace REST/domain modelling more and then use their terminologies. Alternatively why not to do an alternative where you use REST fully and maybe have a behavior model underneath?

On the behavioral model aspect there are plenty of people working on using domain models in the .NET space (DDD or not) who you could reach out to.

Lon28Wall Jan 23, 2009 at 8:27 AM 
We definitely appreciate the feedback... and have made a few updates to clarify a couple of things. However, it seems that there is a misconception about what this app pattern is demonstrating, which is probably a result of some patterns that are used.

The main thing to understand is that we are not using a domain driven design in this pattern. Instead, this uses a domain entity pattern where you model business entities after a domain but do not include business rules in the entities. In other words, these are not business objects but rather data containers modeled after a domain, which is consistent with the Entity Data Model in the .NET Entity Framework. REST resources are defined in the service layer and translators are used to convert between domain entities and REST resources (Entities). In other words, only the contract (resource) is exposed and the implementation (domain entity) is never shared.

The idea is to encapsulate the business layer and associated domain entities behind a facade and only expose structures that represent REST resources. Most CRUD applications are not that complex and you don't need a full blown domain driven design. As a result, the approach here is to use data entities modeled after the domain and implement business rules in business process components that interact with repository components to perform data access operations.

The reason for a repository is that it fits well with the use of the .NET Entity Framework. Entity SQL, uses data entities in the Entity Data Model to define SQL statements, which are converted into Transact SQL. The Repository pattern is based on performing operations against entities and can support complex queries through the use of optional criteria objects.

The following are answers to some of the questions from colinjack... we definitely appreciate the feedback and would be interested in suggestions to help make this design clearer.

"Entity is a massively overloaded term but not one I've ever seen used in the context of REST before."

While I tend to agree WRT the overloading of Entity there really isn't a better term for what these objects represent. In addition, Entity is actuallly farily common in relation to different REST impelementations. Google REST Entity and you'll see different examples, including the Blob REST entity in SQL Data Services.

"How do these layers relate to the REST/domain entities you've discussed previously? Do you consider the resources as bieng part of the presentation layer?"

The bullet that mentioned presentation layer was corrected... the interaction is between the service and business layer. REST Entities are externally exposed and defined in the service layer similar to data contracts in SOAP. Translators in the service layer convert between REST entities and domain entities.

This is similar to initializing ASP.NET controls with domain entities, which are then converted into HTML. The translators initialize REST resource objects with domain entities, and the resource objects are converted into XML for transmission over the wire.

"Transaction script is usually seen as an alternative to a domain model. Repository, as discussed by Evans/Fowler, is about mediating between a domain model and a data mapping layer. Domain entities, at least in terms of a non anemic domain model, are behavioral."

This would be true in a domain driven design; however, as mentioned this is not a domain driven design.

"I know I'm complaining a lot about terminology but wouldn't it be clearer if you wrote this as:

"Use a router to map URIs to handlers that manage the associated resource."

I've re-worded discussions around URI's to focus on handlers versus business components... that was a good catch.

"URIs are not necessarily part of REST and I think its misleading to say that "business components" manage resources."

I agree with the second part of this and have corrected it. However, I would have to disagree with the first part. URI's are a major component of REST. The way to think about REST is to think about how you navigate through a web site. Each page can be represented with a unique URI and you can't get to some without going through others. The interaction through a web site also represents a state machine, which is exactly how the interaction with REST resources should be modeled, and URI's are used to read or modify the state of REST resources. Some resources can also contain URI's to other resources that you couldn't access until first accessing the original URI.

"I'm also wondering what a resource object, are you meaning you create instances of REST entities, so theREST entity is the class and resource object is the object?"

I agree that the termonology could be better here.... and am open to suggestions. The idea is that REST entities represent a definition or class while resource objects represent the instantiation of the class. However, I can see how mixing terms like this can be confusing.

"By parent object do you mean AGGREGATE? Are you not using this term because after referring to business entities you've now switched to "entity data model"."

In a DDD the parent object would be an aggregate root ... however... that term was avoided because it would have made to strong a connection to DDD.

The idea between the two detail diagrams is that one shows patterns while the other shows implementations of the patterns. The thing we're dealing with is that patterns can be used in different ways and architecture is very difficult to describe. For example, I struggle a little with using the transaction script pattern but it's really the best fit for representing business process objects in this design... we could have called it the Business Process pattern... but there is no such thing.

Another thing to keep in mind with this App pattern is that the design used here may seem like overkill... but it promotes strict separation of concerns with a layered approach that can scale out to handle a large number of resources. I've used a similar pattern for web applications that started out around 50 pages or so and have scaled out to several hundered pages over several years without having to change anything in the design.

Hopefully my explinations make things clearer, some changes have been made, and as mentioned we're definitely interested in suggestions that would help make some things clearer.

Thanks!



cromwellryan Jan 23, 2009 at 2:57 AM 
This could be the most over architected solution I've seen in a while. Goodness.

colinjack Jan 22, 2009 at 9:33 PM 
I've worked on quite a few systems using patterns with the names you describe, and have a long term interest in DDD and more recently REST.

I was thus very surprised by this guidance, at best I think its misleading but at worst I think it is leading people in a very bad direction. Although you're using REST/DDD and even messaging patterns/terms it doesn't really seem like this article is a good way to learn about those topics.

Anyway I had some more specific comments.



"The service layer uses a Router pattern to map Uniform Resource Identifiers (URI) to business logic."

Might be worth pointing out its to resources, not just to "business logic".


"The REST Entity pattern is used to define resources exposed by the service."

Entity is a massively overloaded term but not one I've ever seen used in the context of REST before.


"The business layer uses a Façade pattern to implement a message-based interface between the presentation and business layer."

How do these layers relate to the REST/domain entities you've discussed previously? Do you consider the resources as bieng part of the presentation layer?


"Transaction Script objects are used to handle business request processing."
"A Repository pattern is used to access domain entities."
"A Domain Entity pattern is used to define business entities that contain data only."

Transaction script is usually seen as an alternative to a domain model. Repository, as discussed by Evans/Fowler, is about mediating between a domain model and a data mapping layer. Domain entities, at least in terms of a non anemic domain model, are behavioral.

I mention this because I think your use of known pattern names is quite misleading and is more likely to hinder than help.


"Behavior - (REST) Applies to resources that carry out operations. These resources have generally no state of their own and only support the POST operation."

I think your talking here about RPC done over HTTP, a little message processing resource. Its arguable whether this is RESTful, and its odd you don't discuss this pattern later.


"Domain Entity - A set of business objects modeled after a domain that represents the relationship between entities in the domain but does not contain behavior or rules related to the entities. "

I'm surprised that you've chosen to call this an entity, it definitely doesn't match most peoples opinion on what an entity is (in particular in relation to DDD/domain models).


"Entity - (REST) Resources that can be read with a GET operation, but can only be changed by PUT and DELETE operations. "

Entity is not a term I've seen use used in REST, I think the term you should use here is "resource". Also why no POST?


"Entity Translator Implement an object that transforms message data types to business types for requests and reverses the transformation for
responses."

In REST terms I think you're talking about the code that takes the request and works out what to do, including if necessary updating the domain, before mapping back the other way to generate the response. I think it would be clearer if you used established terminology, not least REST terminology.


"Store (REST) Allows entries to be created and updated with PUT."

PUT can be used for creation if you know the entire URI (/users/1) but POST is also an option. Also does a Store really allow "entries" to be created, what layer is this in?


"Transaction (REST) Resources that support transactional operations."

I'm interested in reading more about whne you believe cross resource transactions are useful and how you support them.


"Use a router to map REST URIs to business components that manage the associated resource."

I know I'm complaining a lot about terminology but wouldn't it be clearer if you wrote this as:


"Use a router to map URIs to handlers that manage the associated resource."

URIs are not necessarily part of REST and I think its misleading to say that "business components" manage resources.


"Service layer components provide access to business logic in the application. Service consumers interact with the service layer by passing messages to and from it over a communication channel."

We're talking REST here so saying that we're passing messages to services could be very misleading. It worries me that the reader coming in with RPC tendencies might misread this.


"Represents a resource that can retrieved using GET and can only be updated using PUT and DELETE"

Wondered why you are ignoring POST?


"Business layer components implement the core functionality of the system, and encapsulate the relevant business logic."

Earlier you said that business components managed resources, but you've just described the fact that your resources are part of your "service layer" which sits on top of this layer.


"The service implementation is responsible for translating between external contracts and internal entities and then passing the request on to the business layer façade. "

After mapping to internal entities why not just tell them what you want them to do, why do we need to immediately go procedural by bringing in a business layer facade when an object-oriented domain model is great for representing business logic?


"In order to provide a common interface, a typical approach is to define the façade using an Interface type with a single operation used to handle all requests."

Not sure what this means, you said the service layer maps to internal entities then passes the request (which I assume is the entities) to the business layer facade, but if so how does this relate to having a single method...oh I just read on.


"Business entities are defined that represent entities within the application domain. "

Wondering if problem domain might make more sense than application domain?


"In this scenario you have full control of the database schema and can define business entities based on entities in the domain and the relationships those entities have with each other. "

Why bother if your using transaction script and they have no behavior: http://www.martinfowler.com/bliki/AnemicDomainModel.html


"Technical Solution"

This diagram is very confusing, why are "Business Entities" part of the Data Access Layer?

Also wondering why do you refer to "Resource Objects", you might have a resource handler for a resource and it but even then the request handler is *not* the resource. I'm more than happy to point you at good REST resources for terminology that you might want to use.


"REST entities are defined using resource objects."

No-one I've seen in the REST community uses this sort of terminology and this is more likely to confuse people than to help.

I'm also wondering what a resource object, are you meaning you create instances of REST entities, so theREST entity is the class and resource object is the object?


"Classes are defined that represent REST entities, or resources,"

Might be clearer if you said "Classes are defined that represent resources". I think you might not be doing this as "representations" also have a meaning in REST but it gets rid of the unhelpful "REST entity" idea.


"Define a generic operation that takes the command and message container as parameters and returns the message container. "

I'm not sure what this even means, to me "message container" might mean envelope or something of that sort but I'm truly not clear.


"EmployeeFacade"

Having a message handler that has a switch and then just hands off the data to another component seems like a poor solution.


"Promote(object[] data)"

I'm amazed that this example shows business logic implemented like this, especially given that you're using DDD/domain model terminology elsewhere. Code like "PositionEnum position = data[1] as PositionEnum" just isn't needed these days.


"For example, business process objects can perform get, save, and update operations on business entities without having any knowledge of the underlying data store used to persist the objects."

Thats one way of doing things, but whether this is a good way of doing things is another matter.


"Identify parent objects in your entity data model and define a separate repository object for each one. "

By parent object do you mean AGGREGATE? Are you not using this term because after referring to business entities you've now switched to "entity data model".


"Consider using domain modeling to define the entity data model. "

I realize this is EF talk but using domain modeling to define a data model does sound a little off.