Skip to main content
MindTouch Success Center

Your First API Project

Applies to:
All MindTouch Versions
Role required:
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

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.

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=""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>

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 reference documentation, we see there's a "mode" parameter that lets us access the raw page contents (which are HTML entity encoded). We can load the API URL like so:

$ curl -H 'X-Deki-Token: {signature}'
<content type="application/x.deki0805+xml" title="test">
   <body>&lt;p&gt;Test page.&lt;/p&gt;</body>

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}' > 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
  • 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 POSTbody

  • 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
<?xml-stylesheet type='text/xsl' href='/@api/host/resources/error.xslt'?>
   <title>Bad Request</title>
   <message>'edittime' parameter is not valid</message>

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 reference 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
<edit status="success">
   <page id="353" href="" deleted="false" revision="2">

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

Next Steps

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

  • Was this article helpful?