Getting started with SQLMutation REST API V2

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 with the web client). In order to get started on how to integrate an application using the service, read the following information.

Follow this link to get the main documentation page

NOTE: this API is deprecated. The new V4 API is specified with OpenApi and allows the automatic generation of clients for virtually any language.

Specification of the REST API service

The service resource url is

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


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. This xml can be generated from your database using the XDBSchema tool.
  3. <options> (optional): Additional parameters (see Additional options).


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

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:

Example Requests

Successful request



<sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
<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"/>

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

<?xml version="1.0" encoding="UTF-8" ?>
<version><development /></version>
<sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>
<equivalent />
<sql>  SELECT DISTINCT empname FROM staff WHERE empnum = 'E1'</sql>
<sql>  SELECT empname FROM staff WHERE empnum <> 'E1'</sql>
<sql>  SELECT empname FROM staff WHERE empnum > 'E1'</sql>
<sql>  SELECT empname FROM staff WHERE empnum < 'E1'</sql>

Request with errors



<sql>SELECT empname FROM staff WHERE empnum = 'E1'</sql>

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

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