This article explains how to 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.
Step 1: Create a Page
Create a page on your site for testing (
https://yoursite.mindtouch.us/Test) and enter some sample content.
Step 2: Access the API
Every object on the MindTouch site (pages, users, groups, etc.) are available through the API. If the page is public, we can use the "pages" API and visit
https://yoursite.mindtouch.us/@api/deki/pages/=test in a browser:
A few notes:
MindTouch objects can be accessed by name (
@api/deki/pages/=test) or id (
@api/deki/pages/353). To find the id of a page manually, view the source in the browser and look for Deki.PageId.
The default response format is XML, but a JSON response is possible with the
dream.out.format=jsonparameter (i.e. https://yoursite.mindtouch.us/
- The RESTful API is easy to explore with a browser. For example, here's the API response for the homepage of this help site.
Step 3: Access The Page Contents
Browsing the API response for the page, we see an XML document that includes several attributes such as the creation time, permissions, 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://yoursite.mindtouch.us/@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. You can visit http://yoursite.mindtouch.us/
deki/pages/=test/contents to access the page contents:
<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 autogenerated 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:
<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.
Step 4: Edit The Page Contents
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 http://yoursite.mindtouch.us/@api/deki/pages/=test/contents?mode=raw > page.xml
The page contents are now saved in
<content type="application/x.deki0805+xml" title="test"><body><p>Test page.</p></body></content>
Notice the page contents are stored as XML-encoded value. Using a text editor, we can modify the text and save
Step 5: Update The Page Contents API
Let's send the new page information back to the site:
curl -X POST -d @page.xml -u user:pass https://yoursite.mindtouch.us/@api/deki/pages/=test/contents
A few notes:
-X POSTsetting 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).
You can authenticate with standard HTTP Authentication (username/password), or by passing your API key in a header (
-d @page.xmlsends the file contents in the
By default, XML is the assumed input format.
When the request goes through, we see:
$ curl -X POST -d @page.xml -u user:pass https://yoursite.mindtouch.us/@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://yoursite.mindtouch.us/@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 -X POST -d @page.xml -u user:pass https://yoursite.mindtouch.us/@api/deki/pages/=test/contents?edittime=20140226200000 <edit status="success"><page id="353" href="https://yoursite.mindtouch.us/@api/deki/pages/353?redirects=0" deleted="false" revision="2"><uri.ui>https://yoursite.mindtouch.us/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.
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.