Loading

Help documentation

Back to previous page

Murmurs API

Murmurs

Once enabled for your project, the murmurs API can be used to get any Murmurs that are posted to your project and also create a new murmur.

  • None of the Murmurs API capability is available if Murmurs is disabled for your project.
  • 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".

Structure of a murmurs resource

The structure of the murmurs 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.

murmurs resource xml - attributes
  • id: Integer; read only, the system generated id for a murmur. This id is globally unique.
  • author: Resource; details of the user who has created a murmur. If the murmur was posted using Jabber, this will be only available if the user has entered their Jabber user name on their Mingle profile page.
  • body: String; the content of a murmur
  • created_at: Datetime; read only, date and time of a murmur creation.
  • jabber_user_name: String; if the murmur was posted using Jabber, this is the name of the Jabber user who created the murmur.
  • is_truncated: Boolean; indicates if the murmur body is truncated. If the body is truncated, you will need to request that specific murmur to see the full murmur body.
  • stream: XML Element; read only, Where the murmur came from. The type attribute will be either, "comment" or "default". If stream type is "comment", additional information about where the comment was made will be included.

Post a new murmur

Reference

      Request Method: POST
      URL: /api/v2/projects/project_identifier/murmurs.xml
      Parameters: 

      murmur[body]: String.

Example

      POST

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

      murmur[body]="hello there"

Explanation

The above is an example of a POST to create a new murmur in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmur>
  <id type="integer">83</id>
  <author url="http://localhost:8080/api/v2/users/1.xml">
    <id type="integer">1</id>
    <name>bonna</name>
    <login>bonna</login>
    <email>bonna@youremail.com</email>
    <light type="boolean">false</light>
    <icon_path>/user/icon/1/bonnafide.jpg</icon_path>
    <activated type="boolean">true</activated>
    <admin type="boolean">true</admin>
    <version_control_user_name>bonna</version_control_user_name>
    <jabber_user_name>bonna</jabber_user_name>
  </author>
  <body>hello there</body>
  <created_at type="datetime">2009-10-30T10:03:12Z</created_at>
  <jabber_user_name nil="true"></jabber_user_name>
  <is_truncated type="boolean">false</is_truncated>
</murmur>

Get a list of murmurs

You can list all murmurs that are posted to your projects.

Reference

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

Example

      GET

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

Explanation

The above is an example of a GET to list all murmurs in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs type="array">
  <murmur>
    <id type="integer">83</id>
    <author url="http://localhost:8080/api/v2/users/1.xml">
      <id type="integer">1</id>
      <name>bonna</name>
      <login>bonna</login>
      <email>bonna@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path>/user/icon/1/bonnafide.jpg</icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">true</admin>
      <version_control_user_name>bonna</version_control_user_name>
      <jabber_user_name>bonna</jabber_user_name>
    </author>
    <body>hello there</body>
    <created_at type="datetime">2009-10-30T10:03:12Z</created_at>
    <jabber_user_name nil="true"></jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
   ...
  <murmur>
    <id type="integer">71</id>
    <author url="http://localhost:8080/api/v2/users/2.xml">
      <id type="integer">2</id>
      <name>gilbert</name>
      <login>gilbert</login>
      <email>gilbert@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path>/user/icon/2/gilbert.jpg</icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">true</admin>
      <version_control_user_name nil="true">gilbert</version_control_user_name>
      <jabber_user_name>gilbert</jabber_user_name>
    </author>
    <body>Story #1 is dev complete.</body>
    <created_at type="datetime">2009-10-28T09:10:59Z</created_at>
    <jabber_user_name nil="true">gilbert</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
</murmurs>

Get a single murmur

Reference

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

Example

      GET

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

Explanation

The above is an example of a GET to view a specific murmur with an id of 71 in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmur>
  <id type="integer">71</id>
  <author url="http://localhost:8080/api/v2/users/2.xml">
    <id type="integer">2</id>
    <name>gilbert</name>
    <login>gilbert</login>
    <email>gilbert@youremail.com</email>
    <light type="boolean">false</light>
    <icon_path>/user/icon/2/gilbert.jpg</icon_path>
    <activated type="boolean">true</activated>
    <admin type="boolean">true</admin>
    <version_control_user_name nil="true">gilbert</version_control_user_name>
    <jabber_user_name>gilbert</jabber_user_name>
  </author>
  <body>Story #1 is dev complete.</body>
  <created_at type="datetime">2009-10-28T09:10:59Z</created_at>
  <jabber_user_name nil="true">gilbert</jabber_user_name>
  <is_truncated type="boolean">false</is_truncated>
</murmur>

Get a list of murmurs that are associated with a specific card

Any murmurs that contain the 'card keyword + card number', e.g. story 1, #1, will appear on that cards' "Comments/Murmurs" section.

The tab called "Comments/Murmurs" will only appear if Murmurs is enabled for your project.

Reference

      Request Method: GET

      URL: /api/v2/projects/project_identifier/cards/card_number/murmurs.xml

      Parameters: NA

Example

      GET

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

Explanation

The above is an example of a GET to list all murmurs on a card with a card number of 1 in project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following. 

<?xml version="1.0" encoding="UTF-8"?>
<murmurs type="array">
  <murmur>
    <id type="integer">82</id>
    <author url="http://localhost:8080/api/v2/users/3.xml">
      <id type="integer">3</id>
      <name>brad</name>
      <login>brad</login>
      <email>brad@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path nil="true"></icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">false</admin>
      <version_control_user_name nil="true"></version_control_user_name>
      <jabber_user_name nil="true">brad</jabber_user_name>
    </author>
    <body>I completed testing for a story #1.</body>
    <created_at type="datetime">2009-10-30T09:29:44Z</created_at>
    <jabber_user_name nil="true">brad</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
   ...
  <murmur>
    <id type="integer">71</id>
    <author url="http://localhost:8080/api/v2/users/2.xml">
     <id type="integer">2</id>
     <name>gilbert</name>
     <login>gilbert</login>
     <email>gilbert@youremail.com</email>
     <light type="boolean">false</light>
     <icon_path>/user/icon/2/gilbert.jpg</icon_path>
     <activated type="boolean">true</activated>
     <admin type="boolean">true</admin>
     <version_control_user_name nil="true">gilbert</version_control_user_name>
     <jabber_user_name>gilbert</jabber_user_name>
    </author>
    <body>Story #1 is dev complete.</body>
    <created_at type="datetime">2009-10-28T09:10:59Z</created_at>
    <jabber_user_name nil="true">gilbert</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
</murmurs>

Get a list of murmurs since a specific murmur

Reference

    Request Method: GET

    URL: /api/v2/projects/project_identifier/murmurs.xml

    Parameters:
    since_id: murmur id

Example

    GET

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

    since_id=71

Explanation

The above is an example of a GET to list 25 murmurs in project with identifier "test_project" since the murmur with id 71. The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following. 

<?xml version="1.0" encoding="UTF-8"?>
<murmurs type="array">
  <murmur>
    <id type="integer">106</id>
    <author url="http://localhost:8080/api/v2/users/3.xml">
      <id type="integer">3</id>
      <name>brad</name>
      <login>brad</login>
      <email>brad@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path nil="true"></icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">false</admin>
      <version_control_user_name nil="true"></version_control_user_name>
      <jabber_user_name nil="true">brad</jabber_user_name>
    </author>
    <body>I completed testing for a story #1.</body>
    <created_at type="datetime">2009-10-30T09:29:44Z</created_at>
    <jabber_user_name nil="true">brad</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
   ...
  <murmur>
     <id type="integer">74</id>
     <author url="http://localhost:8080/api/v2/users/2.xml">
       <id type="integer">2</id>
       <name>gilbert</name>
       <login>gilbert</login>
       <email>gilbert@youremail.com</email>
       <light type="boolean">false</light>
       <icon_path>/user/icon/2/gilbert.jpg</icon_path>
       <activated type="boolean">true</activated>
       <admin type="boolean">true</admin>
       <version_control_user_name nil="true">gilbert</version_control_user_name>
       <jabber_user_name>gilbert</jabber_user_name>
     </author>
     <body>Story #1 is dev complete.</body>
     <created_at type="datetime">2009-10-28T09:10:59Z</created_at>
     <jabber_user_name nil="true">gilbert</jabber_user_name>
     <is_truncated type="boolean">false</is_truncated>
  </murmur>
</murmurs>

Get a list of murmurs before a specific murmur

Reference

    Request Method: GET

    URL: /api/v2/projects/project_identifier/murmurs.xml

    Parameters:
    before_id: murmur id

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs.xml
    
    before_id=71

Explanation

The above is an example of a GET to list 25 murmurs in project with identifier "test_project" before the murmur with id 71. The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following. 

<?xml version="1.0" encoding="UTF-8"?>
<murmurs type="array">
  <murmur>
    <id type="integer">70</id>
    <author url="http://localhost:8080/api/v2/users/3.xml">
      <id type="integer">3</id>
      <name>brad</name>
      <login>brad</login>
      <email>brad@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path nil="true"></icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">false</admin>
      <version_control_user_name nil="true"></version_control_user_name>
      <jabber_user_name nil="true">brad</jabber_user_name>
    </author>
    <body>I completed testing for a story #1.</body>
    <created_at type="datetime">2009-10-30T09:29:44Z</created_at>
    <jabber_user_name nil="true">brad</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
   ...
  <murmur>
    <id type="integer">23</id>
    <author url="http://localhost:8080/api/v2/users/2.xml">
      <id type="integer">2</id>
      <name>gilbert</name>
      <login>gilbert</login>
      <email>gilbert@youremail.com</email>
      <light type="boolean">false</light>
      <icon_path>/user/icon/2/gilbert.jpg</icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">true</admin>
      <version_control_user_name nil="true">gilbert</version_control_user_name>
      <jabber_user_name>gilbert</jabber_user_name>
    </author>
    <body>Story #1 is dev complete.</body>
    <created_at type="datetime">2009-10-28T09:10:59Z</created_at>
    <jabber_user_name nil="true">gilbert</jabber_user_name>
    <is_truncated type="boolean">false</is_truncated>
  </murmur>
</murmurs>

Also see...