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

Application Scenario: Two-Tier Service App (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


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.


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.


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
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
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
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.


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 Feb 2, 2009 at 8:00 PM by prashantbansode, version 2


No comments yet.