Mingle API

The Mingle API provides access to various kinds of resources in Mingle over HTTP. These resources are available as xml documents. The standard HTTP operation of GET, POST, PUT and DELETE are used to support read, create, update and delete operations on them. Hence performing a GET operation for a card resource would be the equivalent of reading that card, performing a PUT on a user would be the equivalent of updating that user; and so on.

Not all resources support all the operations, as sometimes it doesn't make sense within Mingle to allow those operations. An example is performing a DELETE on a user resource, as users in Mingle cannot be deleted.

The rest of this document is aimed at explaining the various resources, the URLs that each operation can be performed at, and the structure of the xml documents that can be exchanged at that URL.

The following example might serve to explain some of the terms used in the rest of this help.

If you were to use a tool like curl, and execute the command

curl 'http://www.google.com'

to issue a "GET" request to that URL, you would get the HTML contents of the Google home page.

You can consider the Mingle REST API as an extension of that mechanism. Consider the URL "http://user:password@your.mingle.server:8080/api/v2/projects/example_project/cards/42.xml". If you were to issue a "GET" request to that URL, the Mingle server will serve up an xml documentation that is a representation of card number 42, in the project with identifier "example_project".

      GET
      
      http://user:password@your.mingle.server:8080/api/v2/projects/example_project/cards/42.xml
    

The above example, although almost trivially simple, illustrates a few basic concepts about the API.

• There is a well known resource, which in this case is the Card
• The resource is available at a particular location, over HTTP. This is the URL of the resource.
• A GET request can be issued to a URL to obtain the contents of the resource that is available at that location.
• Mingle uses basic authentication to authorize the operation. In this case, this is indicated by the "user:password" portion of the URL. In the sections below you will find more information on how to turn on basic authentication for Mingle.
• The resource is served up as xml in this example.
• The URL to get the resource over the REST API, is the same as the URL if you were to see a card's contents using the browser

What though, if you wanted to send parameters to the server to update, delete or create a new resource?

In RESTful terms these operations map onto HTTP operations as follows

• POST => Create (can also be used to Update and Delete)
• GET => Read (which we have already seen in the above example)
• PUT => Update (can also be use to Create)
• DELETE => Delete

Thus all database CRUD (create, read, update, delete) operations have a HTTP equivalent. While this is by no means what REST is about, this easy mapping means that a client can manipulate various resources just as easily as they would with a programmatic API that allowed for direct manipulation of database state.

For GET requests, parameters to the server follow the familiar "query-string" mechanism, where they can be sent appended to the URL.

For PUT/POST requests, the parameter name value pairs need to be sent to the server as follows

      PUT
    
      http://user:password@your.mingle.server:8080/api/v2/projects/my_project/cards/17.xml
      
      card[name]=some_name
      card[card_type_name]=story
    

If you were to issue the PUT request above to that URL, with the parameters as shown the Mingle server will update the card with the card number 17, by setting the name and card_type to "some name", and "story" respectively.

      POST
    
      http://user:password@your.mingle.server:8080/api/v2/projects/my_project/cards.xml
      
      card[name]=some_name
      card[card_type_name]=story
    

If you were to issue the POST request above to that URL, with the parameters as shown the Mingle server will create a card by setting the name and card_type to "some name", and "story" respectively.

• The URL to POST/PUT/DELETE may be slightly different from the GET URL
• To POST a resource to a URL, the resource should be sent as a parameters
• Boolean values can be sent as the strings 'true' or 'false'

• The Mingle REST API can be accessed over any tool capable of making HTTP requests, including, but not restricted to command line tools like curl, and the ruby Net::HTTP library.
• If you plan to use the ruby ActiveResource framework, please note that Mingle only supports ActiveResource 2.0.2 or later.
• For example, user resource has attributes: login and name. The request parameter name of the user resource should be: user['login'] and user['name'].
• REST resources often contain other REST resources. E.g., a card resource includes information about the project that it belongs to. When this happens, the contained resource will generally be an abbreviated version of the resource, with a "url" attribute which points to the full resource.
• Please note that all POST and PUT requests must be in XML format by default. This is not illustrated in the examples above.
• To specify parameters as shown in the examples above you will have to set the request header for Content-Type to "application/x-www-form-urlencoded".

The Mingle API supports basic authentication.

 basic_authentication_enabled: true