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/project/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/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 if 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

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

If you were to issue the above, as a "PUT" request to that URL, with the parameters as shown the Mingle server will update the card with the ID 17, 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 ActiveResource2.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'].

The Mingle API supports basic authentication. However it is disabled in the default configuration.

To enable basic authentication, you need set the basic_auth_enabled configuration option to true in the Mingle data directory/config/auth_config.yml file, where Mingle data directory is the path to the mingle data directory on your installation.

e.g.basic_auth_enabled: true