Preface

matterial-api

Take a look at the matterial-api, which is publicly available at gitlab. This project defines the api-objects.

Basic rest-client

You have to implement a basic rest-client to invoke matterial-api.
A possible implemenation using rest_client to create a basic client:

require 'rest_client'
require 'json'

class MatterialClient

  attr_accessor :session_id

  # Client must be initialized with login and password
  def initialize(options = {})
    @login = options[:login] || 'mail@example.com'
    @password = options[:password] || 'foobar'
    @credentials = {
      login: @login,
      password: @password
    }
    @headers = options[:headers] || {
      'Accept' => 'application/json; charset=UTF-8',
      'Content-Type' => 'application/json; charset=UTF-8'
    }
    @base_uri = options[:base_uri] || 'https://my.matterial.com/mtr-backend/api'
    @session_id = nil
  end

  # Helper method to handle timeouts
  def handle_timeouts
    begin
      yield
    rescue Net::OpenTimeout, Net::ReadTimeout
      {}
    end
  end

  # Helper method to handle excpetions
  def handle_errors
    begin
      yield
    rescue RestClient::ExceptionWithResponse => e
      e.response
    end
  end

  # Helper method to handle respone
  def handle_response(response)
    case response.code
    when 200
      JSON.parse response
    when 404
      nil
    else
      response.return!(request, result, &block)
    end
  end

  ###################
  ## API endpoints ##
  ###################

  # Log in with credentials to get sessiodId
  def logon
    url = "#{@base_uri}/logon"
    response = RestClient.post(url, @credentials.to_json, {content_type: :json, accept: :json})
    @session_id = JSON.parse(response.body)['sessionId']
  end

  # Search for documents
  def search_documents(query, options = {})
    parameters = {query: query}
    parameters.merge! options
    url = "#{@base_uri}/document/search"
    handle_response RestClient.get(url, {cookies: { 'JSESSIONID' => @session_id}, params: parameters } )
  end

  # get all docments
  def get_documents(params = {})
    url = "#{@base_uri}/document"
    handle_response RestClient.get(url, {cookies: { 'JSESSIONID' => @session_id}, params: params } )
  end
  
  # get document by id
  def get_document(id = nil, params = {})
    handle_errors do 
      url = "#{@base_uri}/document/" + id.to_s
      document = handle_response response = RestClient.get(url, {cookies: { 'JSESSIONID' => @session_id}, params: params } )
      if response.code == 200
        download_attachments_for_document(document)
      end
      return document
    end
  end

  # get document by id including file
  def get_document_with_file(id = nil, params = {})
    url = "#{@base_uri}/document/" + id.to_s
    
    response = RestClient.get(url, {cookies: { 'JSESSIONID' => @session_id}, params: params } )
    response.code == 200 ? JSON.parse(response) : nil
    
    response = RestClient.get("#{url}/file", {cookies: { 'JSESSIONID' => @session_id}, params: params } )
    response.code == 200 ? response.body :nil

    return {document: document, file: file}
  end

  # get file for specific document
  def get_file(id = nil, params = {})
    handle_errors do 
      url = "#{@base_uri}/document/#{id.to_s}/file"
      response = RestClient.get("#{url}", {cookies: { 'JSESSIONID' => @session_id}, params: params } )
      response.code == 200 ? response.body : nil
    end
  end

end

Base-path

The base-path of your matterial-app-client should always be:

https://my.matterial.com/mtr-backend/

Examples

First, initialize the client with your credentials:

@client = MatterialClient.new(
  login: 'me@example.com', 
  password: 'foobar'
)

A basic login with username / password

@client.logon

Fetch documents

To fetch all documents (meta-data) from matterial:

@client.get_documents

Load document main content

Matterial stored meta-data and main-content of a document separately, so you have load it accordingly.

@client.get_file(123)