Analysis and Service Modeling with REST

This chapter is from the book 

9.2. REST Service Modeling

The need to build a particular service can originate from various sources and under different circumstances.

For example:

• A service might be identified as being necessary based on a service inventory blueprint that maps out required functions and allocates them to functional contexts that form the basis of existing and future services.
• A service might be identified through change requests when it is determined that new functionality is needed and that this new functionality does not belong in any existing functional service contexts.
• A service might be identified through the analysis of legacy systems not yet encapsulated within the scope of a service inventory.

In any case, the service candidate is typically defined with whatever service capability candidates result from the service-oriented analysis process, during which we carry out a service modeling process that decomposes business process logic into granular actions that form the basis of service capability candidates.

The incorporation of resources and uniform contract features add new dimensions to service modeling. When we are aware that a given service candidate is being modeled specifically for a REST implementation, we can take these considerations into account by extending the service modeling process to include steps to better shape the service candidate as a basis for a REST service contract.

The upcoming REST Service Modeling Process section documents a generic service modeling process optimized for REST services. In preparation for the step-by-step coverage of this process, the next two sections highlight some key characteristics of REST service candidate definition.

REST Service Capability Granularity

When actions are defined at this stage, they are considered fine-grained in that each action is clearly distinguished with a specific purpose. However, within the scope of that purpose they can often still be somewhat vague and can easily encompass a range of possible variations.

Defining conceptual service candidates using this level of action granularity is common with mainstream service modeling approaches. It has proven sufficient for SOAP-based Web services because service capabilities that need to support variations of functionality can still be effectively mapped to WSDL-based operations capable of handling a range of input and output parameters.

With REST service contracts, service capabilities are required to incorporate methods (and media types) defined by an overarching uniform contract. As already discussed in the preceding section, the uniform contract for a given service inventory can be modeled alongside and in collaboration with the modeling of service candidates, as long as we know in advance that REST will act as the primary service implementation medium.

Whereas a WSDL-based service contract can incorporate custom parameter lists and other service-specific features, REST puts an upper bound on the granularity of message exchanges at the level of the most complex or most general purpose method and media type. This may, in some cases, lead to the need to define finer-grained service capabilities.

Figure 9.3 highlights the difference between a service candidate modeled in an implementation-neutral manner, versus one modeled specifically for the REST service implementation medium.

Resources vs. Entities

Part of the upcoming REST service modeling process explores the identification of resource candidates. It is through the definition of these resource candidates that we begin to introduce a Web-centric view of a service inventory. As discussed previously in Chapter 6, resources represent the “things” that need to be accessed and processed by service consumers.

What we are also interested in establishing during the service-oriented analysis stage is the encapsulation of entity logic, as explained in the coverage of the entity service model provided in Chapter 4. As with resources, entities also often represent “things” that need to be accessed and processed by service consumers.

What then is the difference between a resource and an entity? To understand REST service modeling, we need to clearly understand this distinction:

• Entities are business-centric and are derived from enterprise business models, such as entity relationship diagrams, logical data models, and ontologies.
• Resources can be business-centric or non-business-centric. A resource is any given “thing” associated with the business automation logic enabled by the service inventory.
• Entities are commonly limited to business artifacts and documents, such as invoices, claims, customers, etc.
• Some entities are more coarse-grained than others. Some entities can encapsulate others. For example, an invoice entity may encapsulate an invoice detail entity.
• Resources can also vary in granularity, but are often fine-grained. It is less common to have formally defined coarse-grained resources that encapsulate fine-grained resources.
• All entities can relate to or be based on resources. Not all resources can be associated with entities because some resources are non-business-centric.

The extent to which we need to formalize the mapping between business-centric resources and entities is up to us. In the upcoming REST service modeling process there are steps that encourage us to define and standardize resources as part of the service inventory blueprint so that we gain a better understanding of how and where resources need to be consumed.

From a pure modeling perspective we are further encouraged to relate business-centric resources to business entities so that we maintain a constant alignment with how business-centric artifacts and documents exist within our business. This perspective is especially valuable as the business and its automation requirements continue to evolve over time.

REST Service Modeling Process

We now introduce a formal process for modeling REST services. This section is divided into a series of parts that describe each process step. About half of the step descriptions are further supplemented with a string of case study examples that demonstrate how a set of service candidates are defined and refined to form a simple service composition candidate.

Figure 9.4 summarizes the process by providing a variation of the original mainstream service modeling process (first introduced in Chapter 8) containing modifications and additional steps incorporated in support of REST service modeling.

Let’s take a closer look at the individual steps of the REST service modeling process. We’ll begin with a case study example that establishes the business process logic that will act as our primary input into the process steps.

Step 1: Decompose Business Process (into Granular Actions)

We begin by taking the documented business process and breaking it down into a series of granular process steps. This requires further analysis of the process logic, during which we attempt to decompose the business process into a set of individual granular actions.

Step 2: Filter Out Unsuitable Actions

Not all business process logic is suitable for automation and/or encapsulation by a service. This step requires us to single out any of the granular actions identified in Step 1 that do not appear to be suitable for subsequent REST service modeling steps. Examples include manual process steps that need to be performed by humans and business automation logic being carried out by legacy systems that cannot be wrapped by a service.

Step 3: Identify Agnostic Service Candidates

By filtering out unsuitable actions during Step 2, we are left with only those actions relevant to our REST service modeling effort.

A primary objective of service-orientation is to carry out a separation of concerns whereby agnostic logic is cleanly partitioned from non-agnostic logic. By reviewing the actions that have been identified so far, we can begin to further separate those that have an evident level of reuse potential. This essentially provides us with a preliminary set of agnostic service capability candidates.

We then determine how these service capability candidates should be grouped to form the basis of functional service boundaries.

Common factors we can take into account include:

1. Which service capability candidates defined so far are closely related to each other?
2. Are identified service capability candidates business-centric or utility-centric?
3. What types of functional service contexts are suitable, given the overarching business context of the service inventory?

Item #2 on the list of factors pertains to the organization of service candidates within logical service layers based on service models (see Chapter 4). The Entity Abstraction [463] and Utility Abstraction [517] patterns are applied in particular as these provide the necessary criteria used to distinguish:

• business-centric agnostic logic suitable for entity services
• non-business-centric agnostic logic suitable for utility services

Due to the business-centric level of documentation that typically goes into the authoring of business process models and specifications and associated workflows, the emphasis during this step will naturally be more on the definition of entity service candidates. The upcoming Identify Utility Service Capability Candidates and Define Utility Service Candidates steps are dedicated to developing the utility service layer.

Finally, Item #3 on the preceding list of factors relates to how we may choose to establish functional service boundaries not only in relation to the current business process we are decomposing, but also in relation to the overall nature of the service inventory. This broader consideration helps us determine whether there are generic functional contexts that we can define that will be useful for the automation of multiple business processes.

Step 4: Identify Process-Specific Logic

Any parts of the business process logic remaining after we complete Step 3 will likely need to be classified as non-agnostic or specific to the business process. Common types of actions that fall into this category include business rules, conditional logic, exception logic, and the sequence logic used to execute the individual business process actions.

Process-specific logic is separated into its own logical service layer, as per the Process Abstraction [486] pattern. For a given business process, this type of logic is commonly grouped into a single task service or a service consumer acting as the composition controller.

Step 5: Identify Resources

By examining the functional contexts associated with individual actions we can begin to make a list of how these contexts relate to or form the basis of resources. It can be helpful to further qualify identified resources as agnostic (multi-purpose) or non-agnostic (single-purpose), depending on how specific we determine their usage and existence are to the parent business process.

Step 3 explained how labeling a service candidate or a service capability candidate as “agnostic” has significant implications as to how we approach the modeling of that service. This is not the case with resources. From a modeling perspective, agnostic resources can be incorporated into agnostic service and capability candidates without limitation. The benefit to identifying agnostic resources is to earmark them as parts of the enterprise that are likely to be shared and reused more frequently than non-agnostic resources. This can help us prepare necessary infrastructure or perhaps even limit their access in how we model (and subsequently design) the service capabilities that encompass them.

Note that resources identified at this stage can be expressed using the forward slash as a delimiter. This is not intended to result in URL-compliant statements; rather, it is a means by which to recognize the parts of service capability candidates that pertain to resources. Similarly, modeled resources are intentionally represented in a simplified form. Later, in the service-oriented design stage, the syntactically correct resource identifier statements are used to represent resources, including any necessary partitioning into multi-part URL statements (as per resource identifier syntax standards being used).

Step 6: Associate Service Capabilities with Resources and Methods

We now associate the service capability candidates defined in Steps 3 and 4 with the resources defined in Step 5, as well as with available uniform contract methods that may have been established. If we discover that a given service capability candidate requires a method that does not yet exist in the uniform contract definition, the method can be proposed as input for the next iteration of the Model Uniform Contract task that is part of the service inventory analysis cycle.

We continue to use the same service candidate and service capability candidate notation, but we append service capability candidates with their associated method + resource combinations. This allows for a descriptive and flexible expression of a preliminary service contract that can be further changed and refined during subsequent iterations of the service-oriented analysis process.

Step 7: Apply Service-Orientation

The business process documentation we used as input for the service modeling process may provide us with a level of knowledge as to the underlying processing required by each of the identified REST service capability candidates. Based on this knowledge, we may be able to further shape the definition and scope of service capabilities, as well as their parent service candidates, by taking a relevant subset of the service-orientation principles into consideration.

Step 8: Identify Candidate Service Compositions

Here we document the most common service capability interactions that can take place during the execution of the business process logic. Different interactions are mapped out based on the success and failure scenarios that can occur during the possible action sequences within the business process workflow.

Mapping these interaction scenarios to the required service capability candidates enables us to model candidate service compositions. If we have applied the Process Abstraction [486], Entity Abstraction [463], and Utility Abstraction [517] patterns previously, we can establish a composition hierarchy that is likely to fall under the Three-Layer Inventory [513] compound pattern.

It is through this type of view that we can get a preview of the size and complexity of potential service compositions that result from how we defined the scope and granularity of agnostic and non-agnostic service candidates (and capability candidates) so far. For example, if we determine that the service composition will need to involve too many service capability invocations, we still have an opportunity to revisit our service candidates.

It is also at this stage that we begin to take a closer look at data exchange requirements (because in order for services to compose each other, they must exchange data). This may provide us with enough information to begin identifying required media types based on what has already been defined for the uniform contract. Alternatively, we may determine the need for new media types that have not yet been modeled. In the latter case, we may be gathering information that will act as input for the Model Uniform Contract task that is part of the service inventory analysis cycle (as explained earlier, in the Uniform Contract Modeling and REST Service Inventory Modeling section).

Step 9: Analyze Processing Requirements

As mentioned in the description for Step 3, the emphasis so far in this service modeling process will likely have been on business-centric processing logic. This is to be expected when working with business process definitions that are primarily based on a business view of automation. However, it is prudent to look under the hood of the business logic defined so far in order to identify the need for any further utility logic.

To accomplish this, we need to consider the following:

• Which of the resources identified so far can be considered utility-centric?
• Can actions performed on business-centric resources be considered utility-centric (such as reporting actions)?
• What underlying utility logic needs to be executed in order to process the actions and/or resources encompassed by a service capability candidate?
• Does any required utility logic already exist?
• Does any required utility logic span application boundaries? (In other words, is more than one system required to complete the action?)

Note that information gathered during the Identify Automation Systems step of the parent service-oriented analysis process will be referenced at this point.

Step 10: Define Utility Service Candidates

In this step, we group utility-centric processing steps according to predefined contexts. With utility service candidates, the primary context is a logical relationship between capability candidates. This relationship can be based on any number of factors, including:

• association with a specific legacy system
• association with one or more solution components
• logical grouping according to type of function

Various other issues are considered once service candidates are subjected to the service-oriented design process. For now, this grouping establishes a preliminary utility service layer.

Step 11: Associate Utility-Centric Service Capabilities with Resources and Methods

Here we break down each utility logic processing requirement we identified in Step 9 into a series of granular actions. As with Step 6, we associate resources and methods with actions to establish a set of REST-friendly service capability candidates.

Step 12: Apply Service-Orientation

This step is a repeat of Step 7 provided here specifically for any new utility service candidates that may have emerged from the completion of Steps 9 and 10.

Step 13: Revise Candidate Service Compositions

Now we revisit the original service composition candidate scenarios we identified in Step 8 to incorporate new or revised utility service candidates. The result is typically an expansion of the service composition scope where more utility service capabilities find themselves participating in the business process automation.

Step 14: Revise Resource Definitions

Both business-centric and utility-centric resources can be accessed or processed by utility services. Therefore, any new utility-related processing logic identified in the preceding steps can result in opportunities to further add to and/or revise the set of resources modeled so far.

Step 15: Revise Capability Candidate Grouping

This final step in the REST service modeling process asks us to check the grouping of all modeled service capability candidates.

Reasons why we may need to make further adjustments to these groupings include:

• Utility service capability candidates defined in Steps 9 and 10 may remove some of the required actions that comprised entity service capability candidates defined earlier, in Step 3.
• The introduction of new utility service candidates may affect (or assimilate) the functional scopes of already defined utility service candidates.
• The modeling of larger and potentially more complex service composition candidates in Step 13 may lead to the need to reduce or increase the granularity of some service capability candidates.

Additional Considerations

The preceding service modeling process was presented with the assumption that it is being carried out during the first iteration of the service inventory analysis cycle. Subsequent iterations will have already produced entity service candidates, utility service candidates, resources, and various input for uniform contract methods and media types. As a result, subsequent execution of Steps 3, 5, 8, 9, 10, and 14 will require an extra discovery task during which we determine what relevant service candidates, resources, and uniform contract properties exist, prior to defining or proposing new ones.