Skip to main content
MindTouch Success Center

Getting Started With the API

Applies to:
All MindTouch Versions
Role required:
Admin
If you are looking to extend the functionality of your MindTouch site into other systems, this article explains the basics of the MindTouch API.

Why Do I Need the API?

MindTouch provides out of the box, easily configurable, integrations in the form of Touchpoints. Touchpoints extend your content into other web applications, CRM's, or websites. However, MindTouch can integrate with applications and systems without a web presentation, such as voice assistants and IoT devices. In addition, integrations with publishing automation systems, user management, and translation management systems can be desirable when MindTouch becomes a critical piece of your organization's business. 

These types of integrations typically require more complexity and application programming skills. While the MindTouch API can be easy to use to quickly fetch or update content on the fly, it's value is realized when integrations unlock the ability to extend MindTouch functionality into key parts of an organization.

Technical Details

The MindTouch API is organized around REST, and is located at the /@api/deki relative URL on a MindTouch site.

https://example.com/@api/deki

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

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 a dream.out.format=json HTTP query parameter.

// XML-encoded response
https://example.com/@api/deki/pages/{id}/info

// JSON-encoded response
https://example.com/@api/deki/pages/{id}/info?dream.out.format=json

Authorization

The MindTouch API can receive three types of tokens to allow access to MindTouch site data.

Auth Token

Auth tokens (often stylized as authtoken) are set as HTTP cookies in a user's web browser after authentication. MindTouch auth tokens are generated by a MindTouch site and are cryptographically signed to prevent tampering.

Browser API Token

Browser API tokens are sent from a website, web application, or simply anything that runs in a web browser to the MindTouch API. Implementations with browser API tokens are written in web browser executable languages such as JavaScript.

Normally, web browsers such as Google Chrome or Mozilla Firefox do not allow JavaScript applications running on one website to access data from another. Browsers block cross-origin requests and responses due to the security issues it can cause, especially if one website's JavaScript application uses the cookies of another website to impersonate a user's identity for nefarious purposes. However, a website can declare which third party websites can securely access its data using Cross Origin Resource Sharing (CORS). Browser API tokens allow developers to implement CORS in a safe and secure manner. In addition to CORS, browser API tokens also allow same origin API access from JavaScript executed in content on a MindTouch site to the same site's API.

A browser API token has no specific user permissions for the API to determine which operations are or aren't allowed. User permissions are determined by the web browser session's authtoken HTTP cookie. If the user accessing the integration has not signed in to the MindTouch site, then the API considers the user to be an anonymous user.

Creating web browser integrations with the MindTouch API
Create integrations between the MindTouch API and websites, web applications, Google Chrome apps, or simply anything that runs in a web browser.
Pages: 4

Server API Token

Server API tokens are used to create integrations between a server application, IoT, bots, or anything that can communciate over HTTPS, and the MindTouch API. Implementations with server API tokens are typically written in server executed languages such as C#, Java, JavaScript (Node.js), Python, Go, and PHP. The token consists of a key and a secret which are used to sign API requests, allowing valid requests through and rejecting invalid or expired requests. The token secret is meant to be kept in a secure place, and should never be shared or sent across the internet in plain text.

Creating server integrations with the MindTouch API
Create integrations between the MindTouch API and server applications, IoT devices, bots, or anything that can communicate over HTTPS.
Pages: 4

 

  • Was this article helpful?