Overview | Run Web Application opens in a new window

Getting started with SQLMutation REST API

SQLMutation exposes a service to generate the SQL mutants from third party applications using a REST API (alternatively, the mutants can be generated interactively from a browser). In order to get started on how to integrate an application using the service, read the following information.
NOTE: The SOAP web service is being deprecated, but it is still accesible here.

1. SQLMutation Overview

Follow this link to get an overview of the mutation operators and new features

2. Specification of the REST API service

The service resource url is http://in2test.lsi.uniovi.es/sqlmutation/api/v2/mutants.xml

The service provides a POST operation that returns an XML string with the mutants of a given SQL query

2.1. Inputs

The mutants.xml method requires a body with an XML string containing three items:

<sql> (required): A string containing the SQL of the query to be mutated.
<schema> (required): A string containing an XML representation of the database Schema.
- See the instructions on how to specify the database schema.
- This xml can be generated from your database using the XDBSchema tool.
<options> (optional): Additional parameters (see Additional options).

2.2. Outputs

The service allways returns http status 200 with a string containing the mutants formatted in an XML document that can be further loaded and processed by any application.

The format of the result is explained below:

The root tag named <sqlmutationws> which contains:

A header tag named <version> which contains a single text with the version number.
A tag named <sql> which contains the SQL statement being mutated.
A tag with the result of the mutation. This can be one of the following:
1. The <error> tag is returned if an error occurred during the mutation process. The text inside displays an explanatory message.
2. The <mutants> tag is returned when the mutation is successful. It contains all mutants generated and, for each of the mutants:
  - A <mutant> tag representing a single mutant. Inside this tag:
    - A set of identification tags that classify the mutant (<id>: a sequence number, <category>: the category of the mutant, <type>: the type of the mutant, <subtype>: the subtype of the mutant)
    - An optional <equivalent/> tag in the case of an equivalent mutant.
    - The <sql> tag that contains a text with the mutated SQL

2.3. Additional options

The third item in the input (optional) is a string which may include a set of options (separated by spaces) enclosed in the tag <options></options>. Enclosed in this tag you may include one or more of the following tags:

noequivalent: If present, the equivalent mutants are ommitted from the output (if this option is not present the equivalent mutants are included and tagged with <equivalent/>).
nomutate=cat1,cat2...: If present, specifies the categories or types that will be omited from the output.
numberjdbcparam: If present, preprocess the sql query to uniquely identify each jdbc parameter. Each parameter reference ? is transformed to ?n? where n is a sequential number. Transformed parameters are used to be replaced by the actual values when evaluating the rule.
formatsql: If present, postprocess each generated rule to give a light formatting by starting the main clause keywords in a new line
hideids: If present, ommits the number of each mutant and version. Only for development.
getparsedsql: If present, includes an additional tag with the original SQL after being processed by the parser. Only for development.

3.Example Requests

Successful request

POST http://in2test.lsi.uniovi.es/sqlmutation/api/v2/mutants.xml

Body:

<body>
  <sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
  <schema>
    <table name="STAFF">
      <column name="EMPNUM" type="char" notnull="true" key="true"/>
      <column name="EMPNAME" type="char"/>
      <column name="GRADE" type="decimal"/>
      <column name="CITY" type="char"/>
    </table>
  </schema>
  <options>nomutate=ir,nl</options>
</body>

Response (mutants on categories IR and NL are are ommited as specified in options):

<?xml version="1.0" encoding="UTF-8" ?>
<sqlmutationws>
<version>2.2.0.dev<development /></version>
<sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
<mutants>
    <mutant><id>1</id><category>SC</category><type>SEL</type><subtype>SLCT</subtype>
    <equivalent />
    <sql>  SELECT DISTINCT empname FROM staff WHERE empnum = 'E1'</sql>
  </mutant>
    <mutant><id>8</id><category>OR</category><type>ROR</type><subtype>RORW</subtype>
    <sql>  SELECT empname FROM staff WHERE empnum <> 'E1'</sql>
  </mutant>
    <mutant><id>9</id><category>OR</category><type>ROR</type><subtype>RORW</subtype>
    <sql>  SELECT empname FROM staff WHERE empnum > 'E1'</sql>
  </mutant>
    <mutant><id>10</id><category>OR</category><type>ROR</type><subtype>RORW</subtype>
    <sql>  SELECT empname FROM staff WHERE empnum < 'E1'</sql>
  ...
</mutants>
</sqlmutationws>

Request with errors