Towards a View-Based Process for Designing and Documenting RESTful Service Architectures Bruno Costa PPGI/Federal University of Rio de Janeiro (UFRJ) Rio de Janeiro, Brazil brunocosta.dsn@gmail.com Paulo F. Pires PPGI/Federal University of Rio de Janeiro (UFRJ) Rio de Janeiro, Brazil paulo.f.pires@gmail.com Flávia C. Delicato PPGI/Federal University of Rio de Janeiro (UFRJ) Rio de Janeiro, Brazil fdelicato@gmail.com Flávio Oquendo IRISA-UMR/CNRS Université de Bretagne-Sud Vannes, France flavio.oquendo@irisa.fr ABSTRACT Representational State Transfer (REST) is an architectural style for service-based design. Regarded to be used in massively distributed and loosely coupled hypermedia systems, REST has been the de facto architecture style for REST-based web services (called RESTful services). Besides business functionality, RESTful services should address quality attribute requirements, which are commonly described in scenarios (textual descriptions of how to achieve such attribute in the system s context). However, to properly mapping scenarios into architectural elements is a non-trivial task. Furthermore, architects often fail to document adequately the design decisions taken during such mapping. These issues can result in low-quality RESTful services. In this paper, we present a view-based process that provides mechanisms to represent quality attribute scenarios as concrete design decisions that can be later used in the design of RESTful service architectures. Categories and Subject Descriptors D.2.11 [Software Engineering]: Software Architectures Data abstraction, Languages, Patterns. General Terms Design, Verification, Documentation. Keywords Rest, architectural decisions, model-driven architecture. 1. INTRODUCTION Views and viewpoints have been used to describe software architectures since the establishment of Software Architecture as a distinct discipline in the early 90s [11]. After 25 years, the usage of multiple views is a common practice in software design [4]. In this context, ISO/IEC 42010 standard [18] provides a widely accepted conceptual definition of architectural views, viewpoints, and models. An architectural view is a representation comprised of one or more architectural elements to address a set of design concerns from a specific viewpoint; while an architectural viewpoint is a specification of elements and conventions available Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. ECSAW '15, September 07-11, 2015, Dubrovnik/Cavtat, Croatia 2015 ACM. ISBN 978-1-4503-3393-1/15/09 $15.00 DOI: http://dx.doi.org/10.1145/2797433.2797485 for constructing and using an architectural view. A view may consist of one or more models, which can be represented in diagrams. In turn, each diagram is developed using a set of graphical icons and conventions for visual representation from an associated language. When designing software, to reuse proven good design structures, the architecture is commonly designed according to existent architectural patterns and styles. In the last years, Representational State Transfer (REST) has been de facto architecture style used to design interoperable systems that exchange their information through web services [17], the so-called RESTful services. However, as demonstrated by [8] and [5], the adoption of RESTful services brings several benefits, but also poses new challenges and risks, primarily because the use of such style is pervasive across architectural modules and components of the system. Particularly important among those risks are failures to address effectively quality attribute requirements, such as Performance and Security, which results in low-quality services. Harrison and colleagues demonstrate another problem related to software design: the architects often fail to document adequately their decisions made during the activity of mapping from quality attribute requirements to architectural elements [7]. This leads to several problems, for instance, when decisions made during subsequent development interactions conflict with the original architectural decisions. In this context, this paper presents a view-based process to deal with the challenge of properly address quality attribute requirements and adequately document architectural decisions in the design of RESTful service architectures. We argue that the quality attribute requirements can be seen as stakeholders concerns and, thus, can be addressed in Quality Attribute Views of the system. Furthermore, in our approach we introduce the concept of Quality Attribute Viewpoints Library, which provides a set of quality attribute viewpoints to be used as foundations to model quality attribute views. In addition to assisting the mapping of quality attribute requirements into the RESTful service architecture, our approach also aims to improve the documentation of architectural decisions taken during such mapping. The remainder of this paper is organized as follows. Section 2 we discuss related work. Section 3 describes the proposed process. We present Exposer in Section 4. Section 5 presents a proof of concept. Finally, Section 6 presents the conclusion and future work.
2. RELATED WORK In the last years, there has been a range of proposals for the design of RESTful services by academia and industry. For example, Mulesoft RAML [13] is a non-proprietary domain-specific language (DSL) that implements standards, like YAML and JSON, to assist developers to create RESTful services. Based on the Eclipse Modeling Project (EMF), EMF-REST [6] enables the generation of RESTful services from Ecore models. was proposed to specify RESTful ser-vices based on a set of metamodels and transformations. Table 1 shows a comparison between our approach and the aforementioned works. The main distinguished features of our work are: (i) to be organized using views; (ii) to consider quality attribute requirements to create RESTful services, and; (iii) to aid in the documentation of architectural decisions. Tool Table 1: Comparison between our approach and related works Associated process MDA capabilities View-based Quality attribute requirements considered Documentation of arch. decisions Our approach Yes Yes Yes Yes Yes Yes Laitkorpi et al. Yes Yes Yes No No No Haupt et al. Yes Yes Yes No No No EMF-REST Yes Yes Yes No No No RAML Yes No No No No No From a research perspective, Laitkorpi and associates from Nokia Research Center, proposed one of the first systematic approaches to applying MDA to build RESTful web services [12]. In their work, they pointed out that the refinement of a functional specification into a RESTful service, which is resource-oriented, is not a trivial task. To deal with such complexity they proposed a set of model transformations, starting from service functionalities, specified in a UML sequence diagram, transformed to a resource model (a UML class diagram that expresses resource elements), followed by the service translation and code generation. Haupt and colleagues [8] present another model-driven approach to developing RESTful services. Such research proposes means to fulfill properly the REST constraints, focusing on uniform interface (U) and stateless (S). The authors advocate that the other constraints (like Client-Server and Code on Demand) are already realized or reflected by the HTTP protocol. An MDA environment 3. PROCESS DESCRIPTION In this section, we describe the proposed view-based process to design RESTful services. The entire process is split into two independent subprocesses: (i) the creation of quality attribute viewpoints library and (ii) the creation of quality attribute views, according to the viewpoints, followed by the generation of the service. The UML activity diagram depicted in Figure 1 shows the process as a whole with its subprocesses, input and output artifacts. We envision two user profiles in our approach: REST Specialist and REST Architect. The REST Specialist is responsible for creating the quality attribute viewpoints library based on REST quality attribute general scenarios and a REST meta-model. The REST Architect is responsible for the creation of the RESTful service views according to quality attributes concrete scenarios and quality attribute viewpoints from the library. Finally, the Figure 1: The proposed view-based process for designing RESTful Services
architect generates the deployable RESTful Service. The proposed process is based on quality attribute scenarios, which are unambiguous and testable structured descriptions of how to achieve such attribute in the system s context [3]. In the literature, there are several studies that prove the efficiency of scenarios to express quality attribute requirements, such as [1][3]. In general, a well-formed scenario has a stimulus and response structure [2]: The system receives a stimulus (stimulus) and some desirable response is observed (response). There are two types of scenarios: concrete and general. The former describes scenarios that are specific to a particular system. The latter describes system independent scenarios, which are commonly used as basis to define the system s concrete scenarios [10]. In the next subsections, we describe in detail each activity with their sub-activities and artifacts. 3.1 Quality Attribute Elements and Parameters Identification The objective of this activity is to identify elements and parameters of a specific quality attribute general scenario in light of a REST meta-model and generates a textual document describing them. Regarding ISO/IEC 42010, such general scenarios are considered as concerns that will be addressed in the viewpoints. In this activity, the REST Specialist analyzes the quality attribute general scenarios in order to identify architectural elements and parameters that the quality attributes are sensitive. To identify and express such elements and parameters, it is used a meta-model that formally describes the REST style concepts and their relations. Such meta-model is the second input of Quality Attribute Elements and Parameters Identification activity. As an example, in this work we borrow the REST meta-model proposed by Schreier in [15] and REST quality attribute general scenarios presented by Costa et al. [6]. The main element in REST architectural style is the resource. A resource represents any important concept in the system domain that we want to make accessible through a service. Designing a RESTful service involves finding resources and their relationships, selecting operations for each resource, and defining data formats for them. The REST meta-model introduces the concept of ResourceType to describe resources of the system domain that can be a PrimaryResourceType, describing a single resource or an AggregationResourceType, which is comprised of two or more single resources. The representation of a resource refers to a media type (element MediaType in the meta-model), which is a hypermedia document that brings any useful information about the state of the resource and links to other associated resources. With the quality attribute general scenarios and the REST metamodel, the REST Specialist identifies the elements from the metamodel that are presented in the scenario description with its parameters. For example, the interoperability scenario: A service consumer A requests a resource R1 in a specific format (media type) and receives the representation of the actual state of R1 in response according to the requested format, two architectural elements can be identified: ResourceType and MediaType; the parameter is the format of the media type (e.g. XML, JSON). To perform such identification in the scenario description, the REST Specialist takes into account the detailed description of the metamodel and his/her empirical experience. 3.2 Viewpoint Specification The objective of Viewpoint Specification activity is to create viewpoints that represent the quality attribute general scenarios. To create them, the REST Specialist takes the elements and parameters identified in the Quality Attribute Elements and Parameters activity as an input and generates viewpoint models. Such models are created with a concrete syntax of the REST meta-model. The quality attribute viewpoints created in this activity comprise the quality attribute viewpoints library that will be used by the REST Architect to create quality attribute views. For each quality attribute general scenario, there is a quality attribute view-point. In the following, we describe how the viewpoints library is used by the REST Architect. 3.3 Create Quality Attribute Views To create views, the first input is a RESTful service architecture Figure 2: Applying views in RESTful Service Architecture
model. Such model must be created with the same concrete syntax of the viewpoints. The second input is the quality attribute requirements for the service described as quality attribute concrete scenarios. As a result of this activity, we have a set of quality attribute views of the RESTful service, each one addressing a specific quality attribute concrete scenario and the rationale used to specify them. The sub-activities of this activity and their artifacts are depicted in the UML activity diagram depicted in Figure 2. To create the views and generate the service (next activity), we recommend the support of an MDA tool in order to perform some activities automatically. In our approach, we propose the Exposer 1, an MDA 2 tool that offers capabilities for the specification, analysis, code generation and deployment of RESTful services. In Section 4 we provide more details about Exposer. In the following, we describe the activities on how the REST Architect uses the viewpoint library (Figure 2). Once the RESTful service architecture was created, the REST Architect analyzes the concrete quality attribute scenarios in order to address them in the architecture. Such scenarios provide the parameters that must be configured in the quality attribute views that will be created. First, the architect selects the respective quality attribute viewpoint from the library. After selecting the viewpoint, Exposer verifies if the elements and parameters from the quality attribute viewpoint were addressed in the service architecture (this means that all elements that exist in the quality attribute viewpoint must be in the architecture model). If so, Exposer hides the model elements that are not related to the quality attribute viewpoint, and shows only the elements related to the quality attribute viewpoint (note that, even if the service architecture model is comprised of several elements, Exposer will show only the elements related to the viewpoint to compose the quality attribute view of the service). After, Exposer exhibit the elements related to the viewpoint in order to REST Architect configure the required parameters. However, if Exposer could not find all elements and parameters related to the quality attribute viewpoint in the service architecture model, it will ask to the REST Architect if he/she wants to create such quality attribute view. When the architect confirms the creation of the view, Exposer includes the elements related to the view-point in the service architecture model and asks the architect to configure the related parameters. The specification of the quality attribute views and related configuration of their parameters are architectural decisions made by the REST architect in order to map quality attribute requirements into architectural elements. The rationale about architectural decisions is also registered as a textual description in the created view. Therefore, each view addresses a concrete scenario and the rationale to create them is registered in order to promote the documentation about the design decisions. 3.4 Generate the RESTful Service After creating the quality attribute views, the architectural elements are ready to be used to generate a deployable RESTful service. 4. EXPOSER Exposer is an MDA tool conceived to support the proposed viewbased process to develop RESTful services. Exposer implements 1 Exposer website: http://ubicomp.nce.ufrj.br/exposer 2 Model-Driven Architecture: http://www.omg.org/mda/ the extended Schreier s REST meta-model described in Subsection 2.1as the basis for its modeling language. Exposer is comprised by two components, namely Modeling Workbench, and Service Generator. The tool is an Eclipse IDE plugin created by exploring the capabilities provided by Eclipse Modeling Framework (EMF) [16] and related frameworks. The Exposer Modeling Workbench is used by both REST Specialists and REST Architects to create the quality attribute viewpoints library and the RESTful services views. The REST concepts presented in Subsection 2.1 compose the abstract syntax of the design language used in the modeling workbench. Based on such meta-model, we develop the concrete syntax as shown in Figure 3. In the palette, the section Quality Attribute Viewpoints Library contains three examples of quality attribute viewpoints. Figure 3: Exposer Modeling Workbench The Service Generator component is responsible to generate deployable RESTful services according to the service architecture model created in the Modeling Work-bench. For this task, the architect just has to configure the desired REST framework to be used in the service implementation, such as or RESTEasy [14]. The generated service can be deployed on application servers that implement the chosen framework. For example the JBoss [9]. 5. PROOF OF CONCEPT This Section presents a proof-of-concept aimed at verifying whether, by following the proposed process and using Exposer, a given a set of quality attribute requirements can be properly addressed in the service architecture. Moreover, we aim to assess if the architectural decisions are adequately documented. Finally, the result of the process should be a deployable service that follows such architectural decisions. 5.1 Creating Quality Attribute Viewpoints Library According to the process presented in Section 3 the first activity to be conducted by the REST Specialist is the identification of elements and parameters that the quality attribute is sensitive in order to generate the quality attribute viewpoints that will comprise the library. Such library can be used in any RESTful services design, however, in the proof-of-concept we will present the creation of the quality attribute viewpoint library followed by the subprocess to analyze the service architecture and generation of RESTful Services. To create the viewpoint models, we will use two REST quality attribute general scenarios as proposed by Costa and colleagues [5] and described in Table 2.
Table 2: Interoperability and reliability general scenarios Quality Attribute Interoperability Reliability General Scenario A service consumer A requests a resource R1 in a specific format (media type) and receives the representation of the actual state of R1 in response according to the requested format A service consumer A requests a resource R1 in a specific version specified directly in the URI and receives the representation of the actual state of R1 in the response message. Analyzing the interoperability general scenario, two architectural elements can be identified, ResourceType and MediaType. Furthermore, the parameter is the format (e.g. XML, JSON) that the resource will be represented. In Exposer, to create the viewpoint model, in addition to such identified elements, the REST Specialist can include other ones that he/she consider as important to the quality attribute. The idea is that the views that are based on the viewpoint must contain all elements addressed in the viewpoint by the specialist and their respective configured parameters. In our example, the viewpoint specifies that the related interoperability views must contain at least one aggregation resource with at least one primary resource and a media type associated and configured (the name and extension of the format). The interoperability viewpoint model is depicted in Figure 4 (a). There are two elements identified in the reliability general scenario in Table 2: ResourceType and Version; the parameter is the definition of the resource version. The reliability viewpoint model defines that it is necessary at least one AggregationResource and one PrimaryResource in a reliability view, and the definition of its version is required, as depicted in Figure 4 (b). 5.2.1 Service Example: Bookstore Suppose that a bookstore wants to create a RESTful service to expose the information about their books and magazines via the web. The business goal is to provide means to third-party developers and companies create applications that use the information about their books. In the example, we will consider the interoperability and reliability concrete scenarios described in Table 3, created in light of the general scenarios described in Table 2: Table 3: Interoperability and reliability general scenarios Quality Attribute Reliability Testability Concrete Scenarios (CSs) CS1- A service consumer External_App requests a resource Book in a specific version specified directly in the URI and receives the representation of the actual state of Book in the response message. CS2- The developer of a Bookstore service consumer finds clear and up-to-date documentation of the service. 5.2.2 The RESTful Service Architecture of the Bookstore To create views, the first input is a RESTful service architecture model. This model can be seen as a structural view that contains the elements of the RESTful service, such as resources and media types, responsible for specifying the information that will be exposed by the service. Figure 5 depicts the RESTful service architecture model for the bookstore example. Figure 4: REST interoperability quality attribute viewpoint model (a); (b) REST reliability viewpoint model 5.2 Analysis of the Service Architecture and Generation of RESTful Services Once the quality attribute viewpoint library has been created, the REST Architect can analyze the RESTful service architecture in light of quality attribute concrete scenarios, create views for each quality attribute, and finally generate the RESTful service. (a) (b)
Figure 5: The RESTful Service Architecture of the Bookstore 5.2.3 Bookstore Service Architecture Analysis With the service architecture model, the architect must analyze the model in order to create quality attribute views. In the bookstore service, there are three quality attribute requirements, specified by concrete scenarios in Table 3 (interoperability and reliability). Starting the analysis from the interoperability concrete scenarios, they specify that the resource must be represented by two different media types, thus the architectural decision was to specify two media type elements to the bookstore service, configuring XML and JSON as formats. To realize such decision in the service model, the architect selects the related viewpoint from the viewpoints library palette and Exposer automatically verifies if all viewpoint elements (at least one AggregationResource, one PrimaryResource and one related MediaType) exist in the service model. Since the viewpoint elements are missing, Exposer asks the architect to configure at least one media type (in the example, XML). As the concrete scenario describes that the service must have two media types, the architect includes another one manually, configuring the media type parameter as JSON format. For the reliability concrete scenario, the architectural decision was to configure the version 1.0.0 to the service model. After the architect selects the related viewpoint, Exposer verifies that all elements of reliability viewpoint model (AggregationResource and PrimaryResource) are presented in the service architecture model, however, the version is not configured. So, Exposer asks the architect to configure the version in order to create such reliability view. Fig. 6 (a) depicts the interoperability view and (b) shows the reliability view (with a focus on the resource version) of the bookstore service model. 5.2.4 Bookstore RESful Service Generation The last activity is to generate the RESTful service. The bookstore service generated by the Exposer Service Generator is showed in Figure 7: Deployable bookstore RESful service 6. CONCLUSIONS AND FUTURE WORK In this paper, we presented a view-based process to deal with the challenge of addressing quality attribute requirements in RESTful services and to document the related architectural decisions. The process is supported by an MDA tool, named Exposer, which offers capabilities for the analysis, code generation, and deployment of RESTful services. In our approach, we introduce the concepts of quality attribute viewpoints library and quality attribute view. The library can be used in any RESTful service architecture to address quality attribute requirements through quality attribute views. Furthermore, the quality attribute views also compose the documentation of architectural decisions made in order to address the quality attribute requirements in the service architecture. Thus, the approach provides mechanisms to deal with a major problem in documenting architectural decisions: the knowledge vaporization [17], where architects fail to record their decisions, and such knowledge dissipates. As demonstrated by the proof-of-concept, we believe that by following our proposed process, quality attributes requirements can be addressed in the service architecture model. The architectural documentation is also enhanced once the decisions (a) (b) Figure 6: Interoperability view (a) and the reliability view (b) of the bookstore service Figure 6. The interoperability quality attribute was addressed by the methods that generate XML and JSON media types (lines 12 and 17). In line 7, the version (1.0.0) is defined, addressing the reliability quality attribute requirement. must be modeled as quality attribute views. Finally, by using MDA capabilities of Exposer, it is possible to generate quality RESTful services.
Our current and future work involves the improvements in views and viewpoints designing by using analytic models [8] and Reasoning Frameworks [9], respectively. Another aspect we are very interested in is a systematic evaluation of our process in realworld REST development. 7. ACKNOWLEDGMENTS This work was partially supported by Brazilian Funding Agencies FAPERJ (under grant E-26/110.468/2012 for Flavia C. Delicato) and CNPq (under grant 307378/2014-4 for Flavia Delicato and, 457783/2014-1 and 310661/2012-9 for Paulo F. Pires). We would like to thank Rich Hilliard, Simon Brown, Paulo Merson, and Matthias Naab, who provide valuable comments in discussions related to views and viewpoints in the SATURN Software Architecture Community. 8. REFERENCES [1] F. Bachmann, L. Bass, M. Klein, and C. Shelton. Designing software architectures to achieve quality attribute requirements. Software, IEE Proceedings, 152(4): 153-165, August 2005. [2] L. Bass, M. Klein, and G. Moreno. Applicability of General Scenarios to the Architecture Tradeoff Analysis Method. Technical Report CMU/SEI-2001-TR-014. Software Engineering Institute, Carnegie Mellon University, 2001. [3] L. Bass, P. Clements, and R. Kazman. Software Architecture in Practice. Addison-Wesley, 2012. [4] P. Clements, et al. Documenting Software Architectures: Views and Beyond. Pearson Education, 2010. [5] B. Costa, P. F. Pires, F. C. Delicato, ando P. Merson. Evaluating a Representational State Transfer (REST) Architecture - What is the impact of REST in my architecture? In IEEE/IFIP Conference on Software Architecture (WICSA) Proceedings, pages 105-114. April 2014. [6] EMF-REST: http://emf-rest.com/. Accessed: 2015-03-05. [7] N. B. Harrison, P. Avgeriou, and U. Zdun. Using Patterns to Capture Architectural Decisions. IEEE Software, 24(4): 38-45, July 2007. [8] F. Haupt, D. Karastoyanova, F. Leymann, and B. Schroth. A Model-Driven Approach for REST Compliant Services. In IEEE International Conference on Web Services Proceedings, pages 129 136. June 2014. [9] JBoss AS - Project Documentation: https://docs.jboss.org/author/display/jbasdoc/home. Accessed: 2015-04-13. [10] J. Knodel, and M. Naab. Software Architecture Evaluation in Practice: Retrospective on More Than 50 Architecture Evaluations in Industry. In IEEE/IFIP Conference on Software Architecture (WICSA) Proceedings, pages 115 124. April 2014. [11] P. Kruchten, H. Obbink, and J. Stafford. The Past, Present, and Future for Software Architecture. IEEE Software, 23(2): 22 30, March 2006. [12] M. Laitkorpi, P. Selonen, and T. Systa. Towards a modeldriven process for designing restful web services. In IEEE International Conference on Web Services (ICWS) Proceedings, pages 173-180. July 2009. [13] RAML - RESTful API modeling language: http://raml.org/. Accessed: 2015-03-05. [14] RESTEasy: http://resteasy.jboss.org/. Accessed: 2015-03-14. [15] S. Schreier. Modeling RESTful applications. In Second International Workshop on RESTful Design (WS-REST) Proceedings, pages 15-21. March 2011. [16] D. Steinberg, F. Budinsky, M. Paternostro, and E. Merks. Emf: Eclipse Modeling Framework 2.0 (2nd ed.). Addison- Wesley Professional, 2009. [17] E. Wilde, and C. Pautasso, C. REST: From Research to Practice. Springer Science & Business Media, 2011. [18] ISO/IEC/IEEE 42010:2011 - Systems and software engineering -- Architecture description.