Help

Cards API

Cards

Card resources are located by issuing a GET request to the server with the card's number as a parameter.

Please keep in mind that in all other parts of the system, the system assigned identifier, id, is used to identify a card. If you do not specify the correct card id, you may end up updating the wrong card, and damage your data.

Before you manipulate cards using the API, we recommend that familiarize yourself with some key concepts dealing with cards like card types, and card properties.

Click here to learn more about card types.

Click here to learn more about card properties.

Structure of a card resource

The structure of a card will completely depend on your project, and how you have configured your properties. That said, all cards in all project in Mingle have a few default attributes. In addition to these you will have an attribute for each property definition that you define for your project.

The default 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, number, created_at etc., are provided only as information about the card and cannot be updated through the API.

card resource xml - attributes
  • id: Integer; read only, system assigned unique identifier for a card - do not use this in GET, use number instead.
  • number: Integer; unique identifier of a card within a project.
  • name: String;
  • description: String;
  • card_type_name: String; the name of the card type existing in the project
  • comment: String; only returned in the history version of the card, read only. You cannot specify a comment on create/update of a card.
  • version: Integer; card version, read only. You can specify the version to get history version of the card.
  • project_id: Integer; the id of project having this card, read only.
  • 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 card, read only.
  • created_at: Date Time; date and time of creating card, read only.
  • created_by_user_id: Integer; the id of user who created this card, read only.
  • cp_column_name an attribute for each card property defined for that card type e.g. cp_story_status. Data type will depend on the property.

Locating a card

Reference

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

Example

        GET
      
        http://yourname:password@your.mingle.server:8080/projects/test_project/cards/42.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL of projects/test_project/cards/42.xml represents the card resource for the card numbered 42 in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, you should get a xml document that looks something like the following. 
<?xml version="1.0" encoding="UTF-8"?>
<card>
  <card_type_name>story</card_type_name>
  <cp_feature>api</cp_feature>
  <cp_owner_user_id type="integer"></cp_owner_user_id>
  <cp_priority>urgent</cp_priority>
  <cp_release>R1</cp_release>
  <cp_status>Open</cp_status>
  <created_at type="datetime">2006-04-04T04:33:35Z</created_at>
  <created_by_user_id type="integer">31</created_by_user_id>
  <description></description>
  <has_cross_project_macro type="boolean"></has_cross_project_macro>
  <id type="integer">900</id>
  <modified_by_user_id type="integer">31</modified_by_user_id>
  <name>As an API user, I would like to lookup a card in Mingle, given that I know the card number.</name>
  <number type="integer">42</number>
  <project_id type="integer">2</project_id>
  <updated_at type="datetime">2006-04-07T07:28:23Z</updated_at>
  <version type="integer">3</version>
</card>

Update a card by id

Reference

        Request Method: PUT
        URL: /projects/project_identifier/cards/id.xml
        Parameters: all card attributes that can be updated

Example

        PUT
      
        http://yourname:password@your.mingle.server:8080/projects/test_project/cards/2668.xml
      
        card[name]=new name
        card[card_type_name]=story

Explanation

The above is an example of a PUT request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL of projects/test_project/cards/2668.xml represents the card resource for the card with a system generated id of 2668 in project with identifier test_project. Please not that this is not the card number. The value of the name and card_type_name attributes will get changed the newly specified values of "new name" and "story".

Please keep in mind that this URL uses the card id. If you are not sure what the card id is, look up the card by number, and extract the value of the id attribute. If you do not specify the correct card id, you may end up updating the wrong card, and damage your data.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned a location attribute in the http header of the response, which is a URL to the updated resource.

How to update different kinds of properties
  • Managed/Unmanaged text: Use the text value of the value you would like to update the value to
  • Managed/Unmanaged numbers: Use the numeric value you would like to set the property to
  • Date: Use the date string in the project date format
  • Team member: Use the id of the user you would like to update the value to. You can obtain the user id by looking up the user using the API.
  • Card: Use the id of the card you would like to update the value to. You can obtain the card id by looking up the user using the API. Do not use the card number here.

Create a card

Reference

        Request Method: POST
        URL: POST /projects/project_identifier/cards.xml
        Parameters: all card attributes that can be updated

Example

        POST
    
        http://yourname:password@your.mingle.server:8080/projects/test_project/cards.xml
    
        card[name]=testing card creation
        card[card_type_name]=story

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. Upon execution of this request, the post parameters will be used to create a card on the project with identifier "test_project". The value of the name and card_type_name attributes be set to the specified values of "testing card creation" and "story".

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned a location attribute in the http header of the response, which is a url from which you can get the card resource that was created.

Get a set of cards for a project

Reference

        Request Method: GET
        URL: /projects/project_identifier/cards.xml
        Parameters: 
        
        view : The name of a saved view, whose cards are to be returned back
        page : A specific set of 25 results, if the list contains more than 25 results. The first 25 results are page 1. The next 25 are page 2, and so on. Requesting the contents of a page of data that is past the last valid page, returns the data on the last valid page and not an empty array.
        filters[] : Each value for this parameter represents a filter applied to the list of cards  
        sort : The property whose value will be used to sort the cards returned
        order : ASC/DESC, whether the cards will be returned in Ascending or Descending order of the sort property 
        tagged_with : A comma separated list of tags that will be used to further filter the list of cards in addition to the filters

Example 1

        GET
        
        http://yourname:password@your.mingle.server:8080/projects/test_project/cards.xml

        filter[]=[Type][is][story]
        filter[]=[Status][is not][accepted]
        sort=status
        order=ASC

Explanation

The above is an example of a GET request to a get a filtered set of cards from the project with identifier "test_project". The cards returned will all be of type "Story" and will have a status other than "accepted". They will be returned in the ascending order of their status values, as configured on the property management page in Mingle.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>New</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
    .
    .
    .
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
</cards>

Example 2

        GET

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

        view=Open Stories

Explanation

The above is an example of a GET request to a get all cards in the saved view called "Open Stories" in the project with identifier "test_project".

Result

If you were authorized to perform the operation, and the operation succeeded, you will be an array of card resources, in which each card resource would be a card in the "Open Stories" view. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

<cards type="array">
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
    .
    .
    .
  <card>
    <card_type_name>Story</card_type_name>
    <cp_status>Open</cp_status>
    <cp_group>Profile Module</cp_group>
    ...
  </card>
</cards>

Get all cards for a project

Reference

          Request Method: GET
          URL: /projects/project_identifier/cards.xml?page=all

Example 1

          GET

          http://yourname:password@your.mingle.server:8080/projects/test_project/cards.xml?page=all

Explanation

The above is an example of a GET request to a get all cards from the project with identifier "test_project". This will return all cards for the project.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be an array of card resources. The structure of each card resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

  <cards type="array">
    <card>
      <card_type_name>Story</card_type_name>
      <cp_status>New</cp_status>
      <cp_group>Profile Module</cp_group>
      ...
    </card>
      .
      .
      .
    <card>
      <card_type_name>Story</card_type_name>
      <cp_status>Open</cp_status>
      <cp_group>Profile Module</cp_group>
      ...
    </card>
  </cards>