Web APIs have become first-class citizens on the Web, in particular, to provide a more unified access to heterogeneous data sources that organizations want to make publicly available. While REST APIs have become the norm to structure web APIs, they can be regarded as a server-side solution, offering default limited query capabilities and therefore forcing developers to implement ad-hoc solutions for clients requiring to perform complex queries on the data.
Lately, GraphQL has gained popularity as a way to simplify this work. GraphQL is a query language for Web APIs specially designed to build client applications by providing an intuitive and flexible syntax for describing their data schema, requirements and interactions.
In this post, we present an approach for the generation of GraphQL schemas from UML class diagrams and IFML interaction models, two well-known standard modeling language in the web engineering field, to facilitate the creation of web applications relying on this new GraphQL paradigm following a model-based approach. While UML is used to generate the GraphQL schema, IFML is used to derive the set of queries and modifications to be performed on that schema.
This work complements our previous works studying the combination of models and APIs, including our UML Profile for OData Web APIs and our automatic discovery of Web API Specifications. We will be presenting it at the PRACTI-0-WEB 2017 workshop, co-located with ICWE 2017.
You can read the full paper below or, at the very least, take a look at the slides we used in the presentation of the work
To design and develop open data and services on the Web, organizations may rely on model-driven engineering (MDE) approaches . These kinds of approaches have been widely used in the web engineering community to model and (semi)automatically generate many types of web applications [7, 11, 12]. Typical languages used in this context are UML (or ER and its variations) for the definition of the domain models or data structures and IFML-like languages (that generalizes many other languages proposed by the web engineering community in the past) to express the user interactions.
With the push of Web APIs, which are increasingly becoming first-class citizens on the Web, some MDE approaches have been extended to support organizations looking to publish their data sources online, especially as Representational State Transfer (REST) APIs .
Still, we believe this is not enough to really enable the publication and consumption of open data on the Web. While REST APIs offer many benefits, they can be regarded as, mainly, server-side solutions offering very limited default query capabilities. Therefore, MDE tools can only very partially cover the generation of complete web applications on top of REST APIs, especially if the web application needs to integrate several kinds of (possibly heterogeneous) backends. In those cases, an ad-hoc integration of the external sources is always required [10, 8, 9].
The recent popularization of GraphQL is a very good opportunity to solve this problem. GraphQL is a query language for Web APIs developed by Facebook and released in 2015 for describing the capabilities and requirements of data models for Web applications. A GraphQL document comprises two declarations: a schema declaration defining the types of the objects that can be queried, and the actual queries/modifications to be performed on them. The language has been designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions, offering a seamless and uniform language description to access the data, no matter where this data resides. It is up to the web application server to translate/execute the requests.
Therefore, extending current MDE tools to generate GraphQL specifications from UML and IFML models can be a key tool to facilitate the exploitation of online data sources. To advance in this direction, in this paper we present a set of mappings between both sets of languages. The mapping covers the main UML and IFML elements, which are transformed into GraphQL types and queries respectively.
The rest of the paper is structured as follows. Section 2 presents GraphQL and a running example. Section 3 describes the mapping between UML and GraphQL while Section 4 explores the IFML to GraphQL mappings. Section 5 concludes the paper and presents some future work.
2. Background and Running Example
GraphQL includes two different sublanguages: query and schema. The former, specified by Facebook, is intended for the definition of query and mutation requests on the data, which follows the specific schema defined with the latter. Then the GraphQL server will execute the requests on the backend where the data actually resides.
UML class diagrams may be used to represent the static data organization of GraphQL schemas. To represent the dynamic aspects (queries and modifications) several alternatives exist, including UML behavioral diagrams (sequence diagrams, state machines), OCL expressions (e.g. as part of query operations or contracts) or interaction languages like IFML , the preferred option to express basic user interaction patterns with the data, specially in a web context. Therefore, in this paper we will focus on the UML and IFML mapping to GraphQL, covering the schema and query sublanguages respectively.
To illustrate our approach, we use a running example based on the reference example provided in GraphQL documentation. Figure 1a shows the UML model of our running example, which models the cast of the first trilogy of Star Wars. The model includes classes to represent characters (see Character hierarchy), starships piloted by human characters and reviews for the films. Note that films are modeled as an enumeration type according to the example provided by GraphQL (which also help us to illustrate some mapping specificities). Figure 1b shows an IFML model which illustrates two kind of interaction scenarios involving (1) listing the casting of an episode and the details of a particular character of Star Wars (queries), and (2) adding a review to one of the films (mutation). Given these models, our objective is to obtain the corresponding GraphQL schema. Listing 1.1 shows the GraphQL schema for our running example.
3. UML to GraphQL mapping
UML class diagrams are used to drive the generation of the GraphQL schema definition. Table 1 (upper part) presents an excerpt of the main mappings we have defined for this. The first column indicates the UML metaclass to be mapped while the second column describes the GraphQL snippet to be generated. Due to space limitations, we only comment in detail the transformation of class hierarchies.
Class hierarchies are not supported in GraphQL. Therefore, similarly to UML to relational database implementations , which suffer the same limitation, we have to come up with a strategy to flatten these hierarchies. Among the possible strategies, in this paper, we generate an object type from every concrete class in the hierarchy. Each object type must explicitly contain all the fields inherited or defined by the source class. In addition to the types, we create a set of GrahpQL interfaces that then allows us to manipulate homogeneously all objects of the same “superclass”. Interfaces are generated for every class, including abstract ones. Same as before, each interface must explicitly contain all the fields inherited or defined by the UML element (note that a GraphQL interface is just a collection of field definitions, no explicit operations are defined). Finally, implement relationships are set among the object types generated and their corresponding interfaces, i.e. interfaces generated from every class along with its path to the root.
In our example presented at Figure 1, the UML class hierarchy comprising the abstract class Character and the concrete classes Human and Droid is transformed into the interface Character and the types Human and Droid in the GraphQL schema (see Listing 1.1). Note that both types implements the Character interface and define their own fields together with the ones from the interface.
4. IFML to GraphQL mapping
Every GraphQL Web API has a query type and may have an additional mutation type as root types. They are defined as regular object types, but they are special because they define the entry point of every GraphQL query or mutation. Indeed, those types collect, in form of fields with arguments, all the different queries (or mutations) defined over the schema, as the types Query and Mutation in listing 1.1. In our approach, these special GraphQL types are created from the collection of every query (or mutation) definition generated from the IFML model.
In particular, GraphQL queries and mutations can be generated out of View Component definitions in the IFML model. «list» and «details» stereotypes become queries since they define a view over a data entity by filtering which data objects to show (parameter binding) and which attributes to present (fields). In our example, «list» view component Heroes is transformed into the query casting which is listed in the Query type (root query) of the resulting GraphQL schema. At the same time, the query character with the argument id is created from the «details» Hero details and the parameter binding (id) represented by the navigation flow.
Additionally, «form» stereotyped view components would be transformed into mutations and input types, which collects the data fields parameterizing the invoked mutation. In our example, the «form» view component and its associated action Add are transformed into the mutation createReview which is listed in the Mutation type (root mutation) of the resulting GraphQL schema.
5. Conclusion and Future Work
In this paper, we have presented an approach to generate GraphQL schemas and queries out of UML class and IFML models, respectively. We believe our approach properly aligns with current MDWE approaches enabling designers to deploy their applications into GraphQL-enabled infrastructures. The generated GraphQL document (including both schema and queries/mutations) can be used in any Web application to provide a uniform access to the data.
As future work, we would like to continue expanding our approach to support additional modeling capabilities, like arbitrary query expressions specified in OCL (Object Constraint Language) or other similar languages. We also plan to consider reverse engineering scenarios, where developers want to make existing web applications GraphQL-enabled. Reverse engineering scenarios would require analyzing the current data schema (and querying facilities) to provide the corresponding support in GraphQL. In these scenarios, UML and IFML models could play the role of a pivot intermediate representation between the current platform and the new GraphQL interface. Finally, we would like to explore how to integrate our approach with other tools to create Web applications combining different technologies (e.g., based on REST API generation or OData ).
 Bettini, L.: Implementing Domain-Specific Languages with Xtext and Xtend. Packt Publishing (2013)
 Brambilla, M., Cabot, J., Wimmer, M.: Model-Driven Software Engineering in Practice. Synthesis Lectures on Software Engineering, Morgan & Claypool Publishers (2012)
 Brambilla, M., Fraternali, P.: Interaction Flow Modeling Language. Morgan Kaufmann (2014)
 Ed-douibi, H., Cánovas Izquierdo, J., Cabot, J.: A UML Profile for OData Web APIs. In: Int. Conf. on Web Engineering. p. (to appear) (2017)
 Fielding, R.T.: Architectural Styles and the Design of Network-based Software Architectures (2000)
 Fowler, M.: Patterns of Enterprise Application Architecture. Addison-Wesley Longman Publishing Co., Inc., Boston, MA, USA (2002)
 Fraternali, P.: Tools and Approaches for Developing Data-intensive Web Applications: a Survey. ACM Comput. Surv. 31(3), 227–263 (1999)
 Herzig, D.M., Tran, T.: Heterogeneous Web Data Search Using Relevance-based on the Fly Data Integration. In: World Wide Web Conference. pp. 141–150 (2012)
 Preda, N., Kasneci, G., Suchanek, F.M., Neumann, T., Yuan, W., Weikum, G.: Active Knowledge: Dynamically Enriching RDF Knowledge Bases by Web Services. In: Int. Conf. on Management of Data. pp. 399–410 (2010)
 Quarteroni, S., Brambilla, M., Ceri, S.: A Bottom-up, Knowledge-aware Approach to Integrating and Querying Web Data Services. TWEB 7(4), 19:1–19:33 (2013)
 Rossi, G., Pastor, O., Schwabe, D., Olsina, L. (eds.): Web Engineering: Modelling and Implementing Web Applications. Human-Computer Interaction Series, Springer (2008)
 Valderas, P., Pelechano, V.: A Survey of Requirements Specification in Model-driven Development of Web Applications. TWEB 5(2), 10 (2011)
I’m an IN3 – UOC Postdoctoral Research fellow at SOM Research Team, in Barcelona, Spain. My research interests are mainly focused on Model-Driven Engineering (MDE), Domain-Specific Languages and Collaborative Development.