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
  2. Specification of the REST API
  3. Example Requests
  4. Submit a Software Problem Report/Request for Enhancement
  5. Release notes & new features
  6. Getting started with SQLMutation (Web application)

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:

  1. <sql> (required): A string containing the SQL of the query to be mutated.
  2. <schema> (required): A string containing an XML representation of the database Schema.
  3. <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:
  1. A header tag named <version> which contains a single text with the version number.
  2. A tag named <sql> which contains the SQL statement being mutated.
  3. 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:

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

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

Body:

<body>
  <sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
  <options>nomutate=ir,nl</options>
</body>    

Response (still returns http status 200 but dispalys an error message because schema has not been specified):

<?xml version="1.0" encoding="UTF-8"?>
<sqlfpc>
<version>2.2.0.dev<development/></version>
  <sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
  <error>Generation exception: SQLSchema.load: Table staff is not defined in the schema</error>
</sqlfpc>

4. Submit a Software Problem Report/Request for Enhancement

Open the Web application and then click the button "Submit Problem Report/Request for Enhancement" at the bottom of the form