SCM Configuration API

Mingle supports Subversion, Perforce and Mercurial for source control management. The SCM Configuration API allows you to manage your source integration via the API. To read more about Mingle's source control management please see here.

Please note that all the API resources and examples refer to v2 of the API. If you would like information on v1 of the API please refer to older versions of the help that can be found at the ThoughtWorks Studios website.

Please note that all POST and PUT requests must be in XML format by default. This is not illustrated in the examples here. To specify parameters as shown in the examples you will have to set the request header for Content-Type to "application/x-www-form-urlencoded".

Subversion Configuration API

Structure of a subversion configuration resource

The structure of a subversion configuration resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated field like id are provided only as information about the Subversion configuration and cannot be updated through the API.

subversion configuration resource xml - attributes

id: Integer; read only, system assigned unique identifier for a subversion configuration resource. This is not a project id
marked_for_deletion: Boolean; subversion configuration is a special resource which is not explicitly deleted by the user. Set this flag to true to let Mingle know that this resource needs to be deleted, and the server will delete it asynchronously
project: Resource; name and identifier of a project this Subversion configuration is for; both strings
repository_path: String; the Subversion repository path
username: String
password: String; update only, this field will not be returned on a GET for security reasons

Get the Subversion configuration for a project

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/subversion_configurations.xml
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/subversion_configurations.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request locates the Subversion configuration on a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

Upon execution, you should get an xml document that looks something like the following:

<subversion_configurations type="array">
  <subversion_configuration>
    <id type="integer">23</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>svn://domain/svn/trunk</repository_path>
    <username>svn_login_user_name</username>
  </subversion_configuration>
</subversion_configurations>

Create a Subversion configuration

Reference

    Request Method: POST
    URL: /api/v2/projects/project_identifier/subversion_configurations.xml
    Parameters: 
    subversion_configuration[username]
    subversion_configuration[password]
    subversion_configuration[repository_path]

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/subversion_configurations.xml

    subversion_configuration[username]=readonly_svn_user
    subversion_configuration[password]=t0p53cr3t
    subversion_configuration[repository_path]=svn://path/to/your/repository

Explanation

The above is a POST to create a new subversion_configuration resource. The request creates a new Subversion configuration for a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<subversion_configurations type="array">
  <subversion_configuration>
    <id type="integer">24</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>svn://path/to/your/repository</repository_path>
    <username>readonly_svn_user</username>
  </subversion_configuration>
</subversion_configurations>

Update a Subversion configuration

Reference

    Request Method: PUT
    URL: /api/v2/projects/project_identifier/subversion_configurations/id.xml
    Parameters: 
    subversion_configuration[username]
    subversion_configuration[password]
    subversion_configuration[repository_path]
    subversion_configuration[marked_for_deletion]

Example

    PUT

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/subversion_configurations/24.xml

    subversion_configuration[username]=readonly_svn_user
    subversion_configuration[password]=t0p53cr3t
    subversion_configuration[repository_path]=svn://new_path/to/your/new_repository

Explanation

The above is a PUT to update the subversion_configuration resource with a system generated id of 24 for a project "test_project". It will change the repository path to "svn://new_path/to/your/new_repository". If there was an existing repository configuration, it will be marked for deletion and a new one will be created with this configuration instead. You have to either have "Mingle administrator" or "Project administrator" permissions to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>          
<subversion_configurations type="array">
  <subversion_configuration>
    <id type="integer">25</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>svn://new_path/to/your/new_repository</repository_path>
    <username>readonly_svn_user</username>
  </subversion_configuration>
</subversion_configurations>

Mercurial Configuration API

Structure of a mercurial configuration resource

The structure of a mercurial configuration resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated field like id are provided only as information about the Mercurial configuration and cannot be updated through the API.

Mercurial configuration resource xml - attributes

id: Integer; read only, system assigned unique identifier for a mercurial configuration resource. This is not a project id
marked_for_deletion: Boolean; mercurial configuration is a special resource which is not explicitly deleted by the user. Set this flag to true to let Mingle know that this resource needs to be deleted, and the server will delete it asynchronously
project: Resource; name and identifier of a project this Mercurial configuration is for; both strings
repository_path: String; the Mercurial repository path
username: String
password: String; update only, this field will not be returned on a GET for security reasons

Get the Mercurial configuration for a project

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/hg_configurations.xml
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/hg_configurations.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request locates the Mercurial configuration a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

Upon execution, you should get an xml document that looks something like the following.

<hg_configurations type="array">
  <hg_configuration>
    <id type="integer">23</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project>
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>mercurial://path/to/your/repository</repository_path>
    <username>mercurial_user</username>
  </hg_configuration>
</hg_configurations>

Create a Mercurial configuration

Reference

    Request Method: POST
    URL: /api/v2/projects/project_identifier/hg_configurations.xml
    Parameters: 
    hg_configuration[username]
    hg_configuration[password]
    hg_configuration[repository_path]

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/hg_configurations.xml

    hg_configuration[username]=mercurial_user
    hg_configuration[password]=t0p53cr3t
    hg_configuration[repository_path]=mercurial://path/to/your/repository

Explanation

The above is a POST to create a new hg_configuration resource. The request creates a new Mercurial configuration for a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<hg_configurations type="array">
  <hg_configuration>
    <id type="integer">24</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project>
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>mercurial://path/to/your/repository</repository_path>
    <username>mercurial_user</username>
  </hg_configuration>
</hg_configurations>

Update a Mercurial configuration

Reference

    Request Method: PUT
    URL: /api/v2/projects/project_identifier/hg_configurations/id.xml
    Parameters: 
    hg_configuration[username]
    hg_configuration[password]
    hg_configuration[repository_path]
    hg_configuration[marked_for_deletion]

Example

    PUT

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/hg_configurations/24.xml

    hg_configuration[username]=mercurial_user
    hg_configuration[password]=t0p53cr3t
    hg_configuration[repository_path]=mercurial://new_path/to/your/new_repository

Explanation

The above is a PUT to update the hg_configuration resource with a system generated id of 24 for a project "test_project". It will change the repository path to "svn://new_path/to/your/new_repository". If there was an existing repository configuration, it will be marked for deletion and a new one will be created with this configuration instead. You have to either have "Mingle administrator" or "Project administrator" permissions to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>          
<hg_configurations type="array">
  <hg_configuration>
    <id type="integer">25</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project>
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>mercurial://new_path/to/your/new_repository</repository_path>
    <username>mercurial_user</username>
  </hg_configuration>
</hg_configurations>

Perforce Configuration API

Structure of a perforce configuration resource

The structure of a perforce configuration resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated field like id are provided only as information about the Perforce configuration and cannot be updated through the API.

perforce configuration resource xml - attributes

id: Integer; read only, system assigned unique identifier for a perforce configuration resource. This is not a project id
marked_for_deletion: Boolean; perforce configuration is a special resource which is not explicitly deleted by the user. Set this flag to true to let Mingle know that this resource needs to be deleted, and the server will delete it asynchronously
project: Resource, name and identifier of a project this Perforce configuration is for; both strings
repository_path: String; the Perforce repository path
username: String
password: String; update only, this field will not be returned on a GET for security reasons
host: String
port: Numeric

Get the Perforce configuration for a project

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/perforce_configurations.xml
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/perforce_configurations.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request locates the Perforce configuration a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

Upon execution, you should get an xml document that looks something like the following:

<perforce_configurations type="array">
  <perforce_configuration>
    <id type="integer">23</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project>
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>perforce://path/to/your/repository</repository_path>
    <username>perforce_login_user_name</username>
    <host>host_location</host>
    <port>1666</port>
  </perforce_configuration>
</perforce_configurations>

Create a Perforce configuration

Reference

    Request Method: POST
    URL: /api/v2/projects/project_identifier/perforce_configurations.xml
    Parameters: 
    perforce_configuration[username]
    perforce_configuration[password]
    perforce_configuration[repository_path]
    perforce_configuration[host]
    perforce_configuration[port]

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/perforce_configurations.xml

    perforce_configuration[username]=perforce_user
    perforce_configuration[password]=t0p53cr3t
    perforce_configuration[repository_path]=perforce://path/to/your/repository
    perforce_configuration[host]=host_name
    perforce_configuration[port]=1666

Explanation

The above is a POST to create a new perforce_configuration resource. The request creates a new Perforce configuration for a project with the identifier of "test_project". You have to either have "Mingle administrator" permissions, or be a member of the team to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<perforce_configurations type="array">
  <perforce_configuration>
    <id type="integer">24</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project>
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>perforce://path/to/your/repository</repository_path>
    <username>perforce_user</username>
    <host>host_name</host>
    <port>1666</port>
  </perforce_configuration>
</perforce_configurations>

Update a Perforce configuration

Reference

    Request Method: PUT
    URL: /api/v2/projects/project_identifier/perforce_configurations/id.xml
    Parameters: 
    perforce_configuration[username]
    perforce_configuration[password]
    perforce_configuration[repository_path]
    perforce_configuration[marked_for_deletion]

Example

    PUT

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/perforce_configurations/24.xml

    perforce_configuration[username]=perforce_user
    perforce_configuration[password]=t0p53cr3t
    perforce_configuration[repository_path]=perforce://new_path/to/your/new_repository

Explanation

The above is a PUT to update the perforce_configuration resource with a system generated id of 24 for a project "test_project". It will change the repository path to "perforce://new_path/to/your/new_repository". If there was an existing repository configuration, it will be marked for deletion and a new one will be created with this configuration instead. You have to either have "Mingle administrator" or "Project administrator" permissions to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>          
<perforce_configurations type="array">
  <perforce_configuration>
    <id type="integer">25</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <repository_path>perforce://new_path/to/your/new_repository</repository_path>
    <username>perforce_user</username>
  </perforce_configuration>
</perforce_configurations>