Project and Subversion configuration API

Projects

The Mingle API allows you to setup projects and setup version control system configurations. A project can have only one subversion configuration resource. When you create second subversion configuration resource by REST API, the previous one will be destroyed. This resource is also special in that while it cannot be directly deleted, it can be marked for deletion by setting marked_for_deletion to true in an update call. Mingle will then take care of deleting the resource.

Click here to learn more about setting up projects.

Click here to learn more about subversion configuration.

Structure of a project resource

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.

The structure of a project 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 created_at are provided only as information about the project and cannot be updated through the API.

From the new API version, v2, Mingle does not provide a project_id parameter as it is not used anywhere in the system. The project identifier is used to locate a project.

project resource xml - attributes

name: String
identifier: String, this is used to lookup a project
description: String
created_at: Date Time, date and time of creating project, read only
updated_at: Date Time, date and time of last modification, read only
created_by: Resource, the name and login of the user who created this project info; both String, read only
modified_by: Resource, the name and login of the user who is the last one modified the project info; both String, read only
keywords: XML element, card keywords which are used in this project to reference to a card. Contains keyword XML elements, each of which is a string that is the card keyword. Examples are shown below.
template: Boolean
email_address: String
email_sender_name: String
date_format: String
time_zone: String, time zone location name, for example: 'Beijing', 'Pacific Time (US Attributes & Canada)'
precision: Integer, [0, 10]
anonymous_accessible: Boolean, whether the project allows anonymous access or not
auto_enroll_user_type: String, whether the project will have all users as team members. Users can be enrolled as full, readonly or nil.

Find all projects

Reference

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

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects.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 all project resources available on this instance. If you have "Mingle administrator" permissions, you will get all projects on that instance. If not, you will get a list of all projects that you are a member of.

Result

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

<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <name>Test Project</name>
    <identifier>test_project</identifier>
    <description>
    </description>
    <created_at type="datetime">2009-10-20T10:37:52Z</created_at>
    <updated_at type="datetime">2009-10-21T00:47:55Z</updated_at>
    <created_by url="http://localhost:8080/api/v2/users/8.xml">
      <name>anne</name>
      <login>anne</login>
    </created_by>
     ...
    <date_format>%d %b %Y</date_format>
    <time_zone>Beijing</time_zone>
    <precision type="integer">2</precision>
    <anonymous_accessible type="boolean">false</anonymous_accessible>
    <auto_enroll_user_type nil="true"></auto_enroll_user_type>
  </project>
  .
  .
  .
  <project>
    <name>New Api Project</name>
    <identifier>new_api_project</identifier>
    <description nil="true"></description>
    <created_at type="datetime">2009-10-22T03:11:48Z</created_at>
    <updated_at type="datetime">2009-10-22T03:11:58Z</updated_at>
    <created_by url="http://localhost:8080/api/v2/users/1.xml">
      <name>bonna</name>
      <login>bonna</login>
    </created_by>
     ...
    <date_format>%d %b %Y</date_format>
    <time_zone>Beijing</time_zone>
    <precision type="integer">2</precision>
    <anonymous_accessible type="boolean">false</anonymous_accessible>
    <auto_enroll_user_type nil="true"></auto_enroll_user_type>
  </project>
</projects>

Locating a project by identifier

Reference

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

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project.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 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.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>test project</name>
  <identifier>test_project</identifier>
  <description>
  </description>
  <created_at type="datetime">2009-10-16T07:12:57Z</created_at>
  <updated_at type="datetime">2009-10-19T06:42:21Z</updated_at>
  <created_by url="http://localhost:8080/api/v2/users/1.xml">
    <name>bonna</name>
    <login>bonna</login>
  </created_by>
  <modified_by url="http://localhost:8080/api/v2/users/1.xml">
    <name>bonna</name>
    <login>bonna</login>
  </modified_by>
  <keywords>
    <keyword>card</keyword>
    <keyword>#</keyword>
  </keywords>
  <template type="boolean">false</template>
  <email_address>
  </email_address>
  <email_sender_name>
  </email_sender_name>
  <date_format>%d %b %Y</date_format>
  <time_zone>Beijing</time_zone>
  <precision type="integer">2</precision>
  <anonymous_accessible type="boolean">false</anonymous_accessible>
  <auto_enroll_user_type nil="true"></auto_enroll_user_type>
</project>

Creating a new project

Reference

    Request Method: POST
    URL: /api/v2/projects.xml
    Parameters:
    project[name]: Required
    project[identifier]: Required
    project[description]
    project[template]
    project[email_address]
    project[email_sender_name]
    project[date_format]
    project[time_zone]
    project[precision]

Example

    POST

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

    project[name]=More test
    project[identifier]=more_test
    project[description]=A project that tests things some more
    project[template]=false
    project[email_address]=fred@example.com
    project[email_sender_name]=Fred
    project[date_format]=%d %b %Y
    project[time_zone]=Singapore
    project[precision]=4

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 8080. The request posts a create request with the parameters as supplied. You have to have "Mingle administrator" permissions to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you will be returned a location attribute in the header of the response, which is a url from which you can get the project resource that was created.

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 is configured to; both String.
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 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/23.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 23 for a subversion identifier 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">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://new_path/to/your/new_repository</repository_path>
    <username>readonly_svn_user</username>
  </subversion_configuration>
</subversion_configurations>

Help