REST API Quick Start Guide
A quick start to get up-and-running with the matterial APIs and start building your matterial integration
Integrating matterial into your app or website can begin as soon as you create a matterial instance, requiring the following steps:
- Sign up with matterial and create your new app instance - it’s free!
- We recommend to invite a dedicated user used by the API, for example a user named api, website or similar.
- Now you can check out our sample clients which will give you a quick start on how to use the actual REST api.
Congrats! Read on to begin integrating matterial.
Overview of a typical API interaction
The term instance (in the API documentation the term data source is used) refers to a matterial environment containing documents, users and all other matterial data.
Since it is possible, that one user owns multiple instances, you have to specify the desired instance to work with in a separate request and the server will answer with a redirect to the actual server hosting your instance (which might be the same that you sent your login request to).
In the documentation the urls are specified like this:
<application-url> of the matterial SaaS site consists of the host https://my.matterial.com and the suffix mtr-backend. So the default
Standard authentication procedure
Matterial uses a cookie
JSESSIONID to handle authentication. The cookie is set after a successful authentication request and must be added in each subsequent request.
The standard procedure looks as follows:
- Send a POST to
<application-url>/api/logon/preloginwith user id and password as payload (json or XML). If successfully authenticated, it returns all instances (data sources) of the current logged on user as json or xml. Also the cookie having the id
- Using the instance id of one of the previously returned data sources, send a GET to
<application-url>/api/logon/login/<instanceId>in order to get a redirect to the actual server hosting your instance.
- Send all subsequent request to the server you have been redirected to.
The redirect url points to the html UI of the matterial instance - for example https://host2.matterial.com/matterial. For the REST API, only use the host part of the redirect url.
Now you can start using the rest of the API.
App - Development: Rest Interface