Getting Started With the API
- Applies to:
- All MindTouch Versions
- Role required:
- Admin
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, the MindTouch API 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 easily used 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.
Do you have further questions? Try consulting the MindTouch API FAQ.
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.
HTTPS
MindTouch API communication is secured with HTTPS. It can be accessed privately and securely by HTTPS compatible clients such as a web browser. The MindTouch API domain (a MindTouch site domain) and any additional domains that are required for integrations must be trusted by the HTTPS compatible client or integration. In order to avoid disruptions when SSL/TLS certificates are rotated for these domains, it is highly recommended to trust certificate authority (CA) root and intermediate certificates, as opposed to the domain's server certificate.
In addition to the MindTouch site domain, integrations with the MindTouch API rely on HTTPS communication with the following domains:
- *.cloudfront.net
- files.mtstatic.com
Responses
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
Some API endpoints may, by default, respond with a application/json; charset=utf-8
media type or an alternative media type. These defaults are noted in the documentation for those specific API endpoints.
Status Codes
MindTouch uses conventional HTTP response status codes to indicate the success or failure of an API request. Status codes in the 2xx
range indicate successful requests. Status codes in the 4xx
range indicate a problem with the request such as a missing URL query parameter or invalid HTTP body format. Status codes in the 5xx
range indicate an unexpected, internal problem with the MindTouch API and can be reported to the MindTouch Support Team.
On rare occasions, an API endpoint is deprecated and removed. If it is replaced with a new endpoint, under most circumstances, the old endpoint will redirect to the new endpoint. In order for backward compatibility to be maintained, it is important that API clients follow the Location
HTTP Header, if a 3xx
range status code is returned in an HTTP response.
Name | Value | Description |
---|---|---|
OK | 200 | The request was processed and completed successfully |
Accepted | 201 | The request was accepted successfully and will be processed in a queue |
Non-Authoritative Information | 203 | The request was accepted, however, due to processing errors, the response contains partially complete data |
Moved Permanently | 301 | The API endpoint was deprecated and replaced with a new location |
Found | 302 | After processing the request, the resource to be returned is located at different URL |
Bad Request | 400 | Invalid or missing request URL query parameter, invalid HTTP body format, or invalid or missing HTTP body parameter value |
Unauthorized | 401 | A request to the authentication API endpoint failed |
Forbidden | 403 | The requested resource is not accessible to due to a permission check or invalid authorization |
Not Found | 404 | The requested resource could not be found |
Not Allowed | 405 | The API endpoint does not support the HTTP method in the request. |
Gone | 410 | The API endpoint was deprecated and was not replaced with a new location |
Errors
There are two possible error response formats that can be received from the MindTouch API. The use of these formats varies between errors and API endpoints, therefore your API integration must be developed to handle both formats. Some response fields have been removed from these examples, as they contain internal MindTouch metadata that is irrelevant to API integrations.
Default Error Format
<error> <exception>{exception}</exception> <message>{message}</message> </error>
Legacy Error Format (Deprecated)
<error> <status>{status}</status> <title>{title}</title> <message>{message}</message> <uri>{uri}</uri> </error>
Name | Type | Description |
---|---|---|
{exception} | string | A unique, namespaced key that identifies the error |
{message} | string | The description of the error or explanation of the problem |
{status} | int | The HTTP status code (ex: 400) |
{title} | string | The HTTP status name (ex: Bad Request) |
{uri} | string | The API endpoint URL |