Help

Project & 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

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 id are provided only as information about the card and cannot be updated through the API.

project resource xml - attributes
  • id: Integer; read only, system assigned unique identifier for a project resource. Do not use this to locate a project, use identifier instead
  • name: String
  • identifier: String, this is used to lookup a project
  • description: String
  • 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]
  • updated_at: Date Time, date and time of last modification, read only.
  • modified_by_user_id: Integer, the id of user who is the last one modified the project info, read only.
  • created_at: Date Time, date and time of creating project, read only.
  • created_by_user_id: Integer, the id of user who created this project info, read only.

Locating a project by identifier

Reference

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

Example

        GET

        https://yourname:password@your.mingle.server:8080/projects/test_project.xml

Explanation

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

Result

Upon execution, you should get a xml document that looks something like the following. 
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <card_keywords>#, story, card, defect, bug, fixed, fix</card_keywords>
  <created_at type="datetime">2007-06-10T00:00:00Z</created_at>
  <created_by_user_id type="integer">1</created_by_user_id>
  <date_format>%d %b %Y</date_format>
  <description></description>
  <email_address>dungeon_master@example.com</email_address>
  <email_sender_name>Administrator</email_sender_name>
  <hidden type="boolean">false</hidden>
  <icon></icon>
  <id type="integer">6</id>
  <identifier>test_project</identifier>
  <modified_by_user_id type="integer">19</modified_by_user_id>
  <name>Test Project</name>
  <precision type="integer">2</precision>
  <template type="boolean">false</template>
  <time_zone>Singapore</time_zone>
  <updated_at type="datetime">2008-04-07T08:44:54Z</updated_at>
</project>
You have to either have "Mingle administrator" permissions, or be a memeber of the team to make this call.

Creating a new project

Reference

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

Example

        POST

        https://yourname:password@your.mingle.server:8080/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, post 8080. The request posts a create request with the parameters as supplied. You have to either 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.

You have to have "Mingle administrator" level privileges to make this call.

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 card 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.
  • project_id: Integer, the id of project having this subversion repository configuration, read only.
  • username: String
  • password: String, update only, this field will not be returned on a GET for security reasons.
  • repository_path: String, the subversion repository path
  • 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.

Get the subversion configuration for a project

Reference

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

Example

        GET
        
        https://yourname:password@your.mingle.server:8080/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, post 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 memeber of the team to make this call.

Result

Upon execution, you should get a xml document that looks something like the following. 
<subversion_configurations type="array">
  <subversion_configuration>
    <id type="integer">1</id>
    <marked_for_deletion type="boolean">false</marked_for_deletion>
    <project_id type="integer">52</project_id>
    <repository_path>svn://domain/svn/trunk</repository_path>
    <username>svn_login_user_name</username>
  </subversion_configuration>
</subversion_configurations>
Requires either Mingle administrator or Project administrator privileges.

Create a subversion configuration

Reference

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

Example

        POST

        https://yourname:password@your.mingle.server:8080/projects/test_project/subversion_configurations.xml


        subversion_configuration[project_id]=52
        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 will be returned a location attribute in the header of the response, which is a url from which you can get the subversion configuration resource that was created.

Update a subversion configuration

Reference

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

Example

        POST

        https://yourname:password@your.mingle.server:8080/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 project with the identifier of "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 a xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>          
<subversion_configuration>
  <id type="integer">83</id>
  <marked_for_deletion type="boolean">false</marked_for_deletion>
  <project_id type="integer">52</project_id>
  <repository_path>svn://new_path/to/your/new_repository</repository_path>
  <username>readonly_svn_user</username>
</subversion_configuration>