You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>The figure on the right illustrates the typical development scenario where JSON-based Web APIs define a set of services, each one returning JSON documents when they are called.</p>
41
41
<p>To select and use these Web APIs, developers usually test each service and reverse engineering the implicit structure of the data they return. When developers want to compose Web APIs, they look for common elements among the Web APIs, which is not a trivial task and sometime not successful (i.e., when the APIs cannot be composed).</p>
42
-
<p>Our tool applies a discovery process to uncover the domain (i.e., schema) behind JSON-based Web APIs and assist on the discovery of composition links among them. These arre currently the main functionalities provided:</p>
42
+
<p>Our tool applies a discovery process to uncover the schema (i.e., schema) behind JSON-based Web APIs and assist on the discovery of composition links among them. These arre currently the main functionalities provided:</p>
43
43
<ul>
44
-
<li><strong><ahref="#/simple">Simple discovery</a></strong>, which discovers the domain (and data models) from a JSON document.
45
-
<li><strong><ahref="#/advanced">Advanced discovery</a></strong>, which discovers the domain (and data models) from a set of JSON-based services. First, the domain of each JSON-based service is discovered (by using the simple discoverer), then the resulting domains are composed to obtain a general one.
46
-
<li><strong><ahref="#/composer">Composer</a></strong>, which takes a set of API domains, looks for composition links (i.e., common concepts or attributes) and generates a composition graph. The result is used to assist developers to compose APIs. The tool currently incoporates a sequence diagram generator to visualize API compositions.
44
+
<li><strong><ahref="#/simple">Simple discovery</a></strong>, which discovers the schema (and data models) from a JSON document.
45
+
<li><strong><ahref="#/advanced">Advanced discovery</a></strong>, which discovers the schema (and data models) from a set of JSON-based services. First, the schema of each JSON-based service is discovered (by using the simple discoverer), then the resulting schemas are composed to obtain a general one.
46
+
<li><strong><ahref="#/composer">Composer</a></strong>, which takes a set of API schemas, looks for composition links (i.e., common concepts or attributes) and generates a composition graph. The result is used to assist developers to compose APIs. The tool currently incoporates a sequence diagram generator to visualize API compositions.
<p>Our tool represents domain information as class diagrams, including concepts (i.e., classes) and their relationships (i.e., attributes/associations), while composition links will be represented as relationships between concepts from different domains.The tool leverages on model-driven techniques to represent both the domain and composition information as models and model associations, respectively.
52
+
<p>Our tool represents schema information as class diagrams, including concepts (i.e., classes) and their relationships (i.e., attributes/associations), while composition links will be represented as relationships between concepts from different schemas.The tool leverages on model-driven techniques to represent both the schema and composition information as models and model associations, respectively.
<p>JSON documents include both metadata (i.e., the name side of the object name/value pair elements) and data (i.e., their value). Note that, however, two objects in the same (or different) JSON document(s) generated by a call to the same service do not necessarily have the same exact structure, e.g., it is possible that some of them include only a subset of the metadata/data, thus removing some name/value pairs (e.g., to reduce network traffic). Therefore, the accuracy of the simple discovery increases when a number of JSON objects to infer their common structure are analyzed.</p>
61
61
62
-
<p>The simple discovery process is therefore launched for each JSON object and has two execution modes: creation and refinement. The former creates a root concept from an object representing a concept not yet existing in the service domain created so far whereas the latter enriches/refines an already existing concept with information coming from new objects representing such concept. </p>
62
+
<p>The simple discovery process is therefore launched for each JSON object and has two execution modes: creation and refinement. The former creates a root concept from an object representing a concept not yet existing in the service schema created so far whereas the latter enriches/refines an already existing concept with information coming from new objects representing such concept. </p>
63
63
64
-
<p>When a JSON object element representing a new concept is considered, the following creation rules are applied to build the corresponding elements in the service domain model (see figure on the left as example):</p>
64
+
<p>When a JSON object element representing a new concept is considered, the following creation rules are applied to build the corresponding elements in the schema (see figure on the left as example):</p>
<p>The composer approach applies a discovery process which first analyzes the domain behind each involved API (using the simple and advanced discoverers) and then takes the discovered domains to obtain composition links. The discovered information is used to render a graph to assist developers to compose APIs. For instance, sequence diagrams are curretnly generated to visualize API compositions. </p>
133
-
<p>Composition links among APIs are discovered by means of matching concepts among their domains and analyzing whether they are part of the input parameters of API services. We have currently defined the following rules:</p>
132
+
<p>The composer approach applies a discovery process which first analyzes the schema behind each involved API (using the simple and advanced discoverers) and then takes the discovered schemas to obtain composition links. The discovered information is used to render a graph to assist developers to compose APIs. For instance, sequence diagrams are curretnly generated to visualize API compositions. </p>
133
+
<p>Composition links among APIs are discovered by means of matching concepts among their schemas and analyzing whether they are part of the input parameters of API services. We have currently defined the following rules:</p>
134
134
</div>
135
135
</div>
136
136
137
137
<divclass="row">
138
138
<divclass="col-md-12">
139
139
<ul>
140
-
<li><strong>Rule C1</strong>. Two domain concepts <code>c1</code> and <code>c2</code> contained in different API domains are considered the same concept if <code>c1.name</code> = <code>c2.name</code>. </li>
141
-
<li><strong>Rule C2</strong>. As an API domain concept can represent several JSON objects, only concept attributes/references found in every JSON object will be considered (calculated by the metadata generated by the advanced discoverer).</li>
140
+
<li><strong>Rule C1</strong>. Two concepts <code>c1</code> and <code>c2</code> contained in different API schemas are considered the same concept if <code>c1.name</code> = <code>c2.name</code>. </li>
141
+
<li><strong>Rule C2</strong>. As a concept can represent several JSON objects, only concept attributes/references found in every JSON object will be considered (calculated by the metadata generated by the advanced discoverer).</li>
142
142
<li><strong>Rule C3</strong>. Two attributes/references <code>a1</code> and <code>a2</code> are considered as similar if <code>a1.name = a2.name</code> and <code>a1.type = a2.type</code>. Otherwise heuristics based on their name/type may be applied (e.g., the number of matching letters in their names must be higher than a given threshold). </li>
143
-
<li><strong>Rule C4</strong>. Two domain concepts <code>c1</code> and <code>c2</code> contained in different API domains are similar if they contain a number of similar attributes/references higher than a given threshold.</li>
144
-
<li><strong>Rule C5</strong>. There exists a composition link between two domain concepts <code>c1</code> and <code>c2</code> contained in different API domains if they are the same (or similar) and <code>c2</code> is an input concept. The source of the composition link will be <code>c1</code> and the target will be <code>c2</code>.</li>
143
+
<li><strong>Rule C4</strong>. Two concepts <code>c1</code> and <code>c2</code> contained in different API schemas are similar if they contain a number of similar attributes/references higher than a given threshold.</li>
144
+
<li><strong>Rule C5</strong>. There exists a composition link between two concepts <code>c1</code> and <code>c2</code> contained in different API schemas if they are the same (or similar) and <code>c2</code> is an input concept. The source of the composition link will be <code>c1</code> and the target will be <code>c2</code>.</li>
<p>Composition links plus the API domains can be used to render a graph where nodes represent concepts/attributes and edges represent composition links or attribute composition. The figure on the left shows an example. Colored nodes in the graph represent the concepts used in each API. Blue nodes represent the concepts used as input to call an API. White nodes represent attributes of the concepts. Nodes are connected by directed edges represented by arrows, which can link nodes from the same or different APIs. Nodes from the same API are linked when there is a reference between the concepts in the API domain, whereas nodes from different APIs are linked when a composition link has been detected.</p>
154
+
<p>Composition links plus the API schemas can be used to render a graph where nodes represent concepts/attributes and edges represent composition links or attribute composition. The figure on the left shows an example. Colored nodes in the graph represent the concepts used in each API. Blue nodes represent the concepts used as input to call an API. White nodes represent attributes of the concepts. Nodes are connected by directed edges represented by arrows, which can link nodes from the same or different APIs. Nodes from the same API are linked when there is a reference between the concepts in the API schema, whereas nodes from different APIs are linked when a composition link has been detected.</p>
<p>The tool provides a Java-based backend, which implements the functionalities commented before The main classes included in the backend are shown in the figure below. The backend defines a set of classes to represent JSON documents (see <code>AbstractJsonSource</code> hierarchy) returned by JSON-based Web services. They are called JSON sources and range from single JSON documents (i.e., <code>SingleJsonSource</code>) to a set of them (i.e., <code>JsonSourceSet</code>). JSON sources can also define the input of the service (i.e., <code>withInput</code>) if it is given as a JSON document. The parsing and management of JSON data is performed by using the <ahref="https://github.com/google/gson">GSON library</a>. </p>
179
-
<p>The main functionalities provided by the tool are implemented in their corresponding classes. The simple discoverer is implemented by the classes <code>JsonSimpleDiscoverer</code> and <code>JsonInjector</code>, which provide the discovery of the domain and the data model, respectively. The advanced discoverer is implemented by the classes <code>JsonAdvancedDiscoverer</code>. Finally, the composer discovery is implemented by the class <code>JsonComposer</code>. Other classes not included in the Figure for the sake of simplicity are in charge of managing the coverage information, the management of models (i.e., loading and saving) and the sequence diagram generator. Our solution leverages on the modeling technology to represent the API domains and the data models. In particular, the tool uses the <ahref="https://eclipse.org/modeling/emf/">Eclipse Modeling Framework (EMF)</a></code>.
179
+
<p>The main functionalities provided by the tool are implemented in their corresponding classes. The simple discoverer is implemented by the classes <code>JsonSimpleDiscoverer</code> and <code>JsonInjector</code>, which provide the discovery of the schema and the data model, respectively. The advanced discoverer is implemented by the classes <code>JsonAdvancedDiscoverer</code>. Finally, the composer discovery is implemented by the class <code>JsonComposer</code>. Other classes not included in the Figure for the sake of simplicity are in charge of managing the coverage information, the management of models (i.e., loading and saving) and the sequence diagram generator. Our solution leverages on the modeling technology to represent the API schemas and the data models. In particular, the tool uses the <ahref="https://eclipse.org/modeling/emf/">Eclipse Modeling Framework (EMF)</a></code>.
180
180
<p>The backend is made web-accessible by means of a set of servlets giving access to the classes implementing the core functionalities. The resulting web API allows using the developed service on any website. The first use of this web API is this webpage itself. </p>
181
181
<pclass="text-center">
182
182
<imgstyle="margin-bottom: 20px; padding:10px;" class="img-thumbnail" src="images/doc-architecture.png" alt="Architecture of the tool"/>
0 commit comments