Help documentation

The Mingle API allows you to setup projects and setup version control system configurations. A project can have only one source repository 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.

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.

project resource xml - attributes

• name: String.
• identifier: String; this is used to lookup a project.
• description: String.
• created_at: Date Time; read only, date and time of creating project.
• updated_at: Date Time; read only, date and time of last modification.
• 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.

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>

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>         
            

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.