Skip to main content
MindTouch Success Center

API 101

Use the MindTouch API to access and modify information on your site.

Use the MindTouch API to access and modify information on your site. After completing this article, you will have performed commands to create, update, and modify content on your site with the MindTouch API.

This article assumes familiarity with an operating system's command line shell (such as bashsh, etc.) and the curl application. The examples in this article leverage a server API token, however most examples can be followed for a web browser integration environment by substituting curl for a JavaScript HTTP client and leveraging a browser API token.

Create a page

Create a page on your site for testing (https://{hostname}/Test) and enter some sample content. The {hostname} placeholder is your MindTouch site hostname.

Access the API

Every resource on the MindTouch site (pages, users, groups, etc.) is available through the API. MindTouch site users can access the API, through the web browser, once they have signed into the MindTouch site. Under most situations, integrations require the use of API tokens to access the API.

NOTE:

  • MindTouch resources can be accessed by name (@api/deki/pages/=test) or id (@api/deki/pages/353)

  • The default HTTP response content type is application/xml; charset=utf-8, but an application/json; charset=utf-8 response is possible if API requests include the dream.out.format=json HTTP query parameter

  • The examples below assume a server to MindTouch API integration is being used. The {signature} placeholder found in the examples below refers to a server API token signature

Read page contents

From the command line run the following:

$ curl -H 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/pages/=test

Browsing the API response for the page, we see an XML document that includes several attributes such as the creation time, permissions, and the user who created the page. If you search for "contents" in the response, you'll see the following attribute:

<contents type="application/x.deki0805+xml" href="https://success.example.com/@api/deki/pages/353/contents"etag="31579b7948b2c3381ee049796f344508"/>

The page contents are not directly included in the summary API response by default, but available by loading the page in the href attribute.

<content type="text/html" title="test">
    <body><p>Test page.</p></body>
    <body target="toc"><em>No headers</em></body>
</content>

This is the rendered version of the page HTML, which includes auto-generated content (such as an empty table of contents). We'd like to access the original page contents before rendering.

Looking at the page contents API, we see there's a "mode" parameter that lets us access the raw page contents. We can load the API URL like so:

$ curl -H 'X-Deki-Token: {signature}' https://success.example.com/@api/deki/pages/=test/contents?mode=raw
<content type="application/x.deki0805+xml" title="test">
    <body><p>Test page.</p></body>
</content>

This version returns the original page contents, in a format we can edit.

Edit page content

Get the raw page content

For this example, we'll use curl to save the API response and edit the page locally. In other programming environments, use a standard HTTP library to perform a request and save the response to a variable.

From the command line, run the following:

$ curl -H 'X-Deki-Token: {signature}' https://success.example.com/@api/deki/pages/=test/contents?mode=raw > page.xml

The page contents are now saved inpage.xml:

<content type="application/x.deki0805+xml" title="test"><body>&lt;p&gt;Test page.&lt;/p&gt;</body></content>

Notice the page contents are stored as XML-encoded value. Using a text editor, we can modify the text and save page.xml.

Update the page with new content

Let's send the new page information back to the site:

$ curl -H 'X-Deki-Token: {signature}' -X POST -d @page.xml https://success.example.com/@api/deki/pages/=test/contents

NOTE:

  • The -X POST setting indicates this a HTTP POST request. Make sure to use the right HTTP verb with the API (GET for accessing data, PUT for creating data, POST for updating, and DELETE for removing)

  • -d @page.xml sends the file contents in the POST

  • By default, application/xml; charset=utf-8 is the assumed input content type

 

When the request completes, we see:

$ curl -H 'X-Deki-Token: {signature}' -X POST -d @page.xml https://success.example.com/@api/deki/pages/=test/contents

<?xml-stylesheet type='text/xsl' href='/@api/host/resources/error.xslt'?>
<error><status>400</status><title>Bad Request</title>
<message>'edittime' parameter is not valid</message>
<uri>https://success.example.com/@api/deki/pages/=test/contents</uri></error>

We haven't included a required parameter, and the API returned an error response. The API is very descriptive if an error has occurred, which makes it simple to debug. Looking at the API documentation, we realize we need to include the "edittime" parameter (in the documentation, optional parameters are listed with a question mark).

Now we can resend the API request with an edit time:

$ curl -H 'X-Deki-Token: {signature}' -X POST -d @page.xml https://success.example.com/@api/deki/pages/=test/contents?edittime=20140226200000

<edit status="success"><page id="353" href="https://success.example.com/@api/deki/pages/353?redirects=0" deleted="false" revision="2"><uri.ui>https://success.example.com/test</uri.ui><title>test</title><path>test</path><namespace>main</namespace><date.created>2014-02-27T02:27:58Z</date.created></page></edit>

The API response was a success, and includes an edit summary in the response.

Next steps

Most API interactions will be similar: querying information using GET requests, and creating or updating information with PUT and POST requests. The MindTouch API documentation includes short samples in C#, PHP and curl to help demonstrate a sample session for each type of request.

The API best practices includes tips for using the API, and several common requests you may wish to perform.

  • Was this article helpful?