Loading
Back to previous page

Wiki API

Wiki

Wiki resources are located by issuing a GET request to the server using the wiki page's identifier as a parameter.

The wiki page's identifier is the wiki page's name with special characters encoded. For example, a wiki page with name "the name" has an identifier of "the_name". Wiki page identifiers for all wiki pages in a project can be retrieved. See the section below, 'Getting all wiki pages for a project'.

Please note that all the API resources and examples refer to v2 of the API. If you would like information on v1 of the API please refer to older versions of the help that can be found at the ThoughtWorks Studios website.

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 the wiki resource

wiki resource xml - attributes
  • id: Integer; read only, system assigned unique identifier for the wiki page.
  • identifier: String; read only, encoded name of the wiki page.
  • name: String; read only, user given name for the wiki page.
  • content: String; the wiki page content.
  • project: Resource; name and identifier of the project of the wiki page; both String.
  • created_at: Datetime; read only, date and time of creating the wiki page.
  • updated_at: Datetime; read only, date and time of updating the wiki page.
  • created_by: Resource; details of the user who created a wiki.
  • modified_by: Resource; details of the user who modified a wiki.
  • version: Integer; read only, current version of the wiki page.

Locating a wiki page

Reference

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

Example

            GET

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

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL projects/test_project/wiki/wiki_identifier.xml represents the wiki resource for the wiki page with identifier "wiki_identifier" (and page name "wiki identifier") in the project with identifier "test_project".

Result

      <?xml version="1.0" encoding="UTF-8"?>
      <pages type="array">
        <page>
          <id type="integer">65</id>
          <identifier>Lofi-Prototype</identifier>
          <name>Lofi-Prototype</name>
          <content>new mockup guidelines</content>
          <project url="http://localhost:8080/api/v2/projects/test_project.xml">
            <name>test project</name>
            <identifier>test_project</identifier>
          </project>
          <created_at type="datetime">2009-11-02T09:20:52Z</created_at>
          <updated_at type="datetime">2009-11-02T09:28:17Z</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/7.xml">
            <name>Tracy</name>
            <login>tracy</login>
          </modified_by>
          <version type="integer">2</version>
        </page>
      </pages>

Updating a wiki page

Reference

          Request Method: PUT
          URL: /api/v2/projects/project_identifier/wiki/identifier.xml
          Parameters: wiki page content

Example 1

          PUT

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

          page[content]=Hello there. This page is updated.

The above is an example of a PUT request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL api/v2/projects/test_project/wiki/hello.xml represents the wiki resource for the wiki page with an identifier of "hello" in the project with identifier "test_project". The wiki page content will be updated with the newly specified content of "Hello there. This page is updated."

Example 2

          PUT

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

          page[content]={{
            pie-chart
              data: SELECT priority, count(*) WHERE type = story
          }}

The above is an example of a PUT request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL api/v2/projects/test_project/wiki/hello.xml represents the wiki resource for the wiki with an identifier of "hello" in the project with identifier "test_project". The wiki page content will be updated with a pie chart.

Creating a wiki page

Reference

          Request Method: POST
          URL: POST /api/v2/projects/project_identifier/wiki.xml
          Parameters: wiki page name and content

Example

          POST

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

          page[name]=testing wiki creation
          page[content]=this is new wiki page content

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 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 wiki page in the project that has identifier "test_project". The value of the name and content attributes will be set to the specified values of "testing wiki creation" and "this is new wiki page content", respectively.

Result

If you are authorized to perform the operation and the operation succeeds, you are given a location attribute in the HTTP header of the response, which is a URL from which you can get the wiki page resource that was created.

Getting all wiki pages for a project

Reference

          Request Method: GET
          URL: /api/v2/projects/project_identifier/wiki.xml
          Parameters: none

Example

          GET

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

Explanation

The above is an example of a GET request to get all existing wiki pages from the project with identifier "test_project".

Result

If you are authorized to perform the operation and the operation succeeds, you are given a list of wiki resources. The structure of each wiki resource is the same as would be obtained if you had issued a GET to obtain a single resource. 

  <pages type="array">
    <page>
      <id type="integer">65</id>
      <identifier>Lofi-Prototype</identifier>
      <name>Lofi-Prototype</name>
      <content>h3. new mockup guidelines</content>
      <project url="http://localhost:8080/api/v2/projects/test_project.xml">
        <name>test project</name>
        <identifier>test_project</identifier>
      </project>
      ...
    </page>
    <page>
      <id type="integer">64</id>
      <identifier>Overview_Page</identifier>
      <name>Overview Page</name>
      <content>This is an overview page</content>
      <project url="http://localhost:8080/api/v2/projects/test_project.xml">
        <name>test project</name>
        <identifier>test_project</identifier>
      </project>
      ...
    </page>
     .
    .
    .
  </pages>