Skip to main content

18.10 Internal REST Webservice Methods

These Web services allow you to do HTTP requests to the specified endpoints (VTE_URL/restapi/v1/vtews/METHOD_NAME).

The requests need POST method, basic authentication (you must set ‘Authentication basic’ into the header which is calculated through a function based on username* and password*) and their relative parameters.
Each one method will give a JSON response with a status and the data or in case of error an error code and its relative message.

Notes:
• The “id” parameter is always specified as ‘moduleid* x recordid’ (ex: 2x313) moduleid*: You can get the the moduleid from webservice ‘describe’ method (idPrefix)

Headers:
• Authorization: Basic base64_encode("username*:password*")
• Content-Type : application/json

username* (VTE) password* (User preferences’ Webservice Access Key)

Authorization Example:
‘Basic ZmVkZXJpY28ucGVybGluOjB5cm5MRjNhS2RhMDZ2c3E=‘


Requirements for Apache2:
• Activate apache rewrite module
• Set AllowOverride All into the virtualhost file to the vte path folder.
Example:

<Directory /var/www/html/VTE_FOLDER>
Options -Indexes +FollowSymLinks +MultiViews
AllowOverride All
Require all granted
</Directory>

Requirements for Nginx + PHP FPM

As Nginx does not handle htaccess file, some special rewrites are needed in order to handle WS requests.
Below an example of nginx conf file:

server {
	listen 80;

	root /var/www/vtenext/;
	
	autoindex off;
	
	index index.php index.html index.htm;

	# Make site accessible from http://localhost/
	
	server_name localhost;

	location / {
		# First attempt to serve request as file, then
		# as directory, then fall back to index.html
		try_files $uri $uri/ index.html;
	}

	# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
	location ~ [^/]\.php(/|$) {
		include snippets/fastcgi-php.conf;
		
		# With php cgi alone:
		#fastcgi_pass 127.0.0.1:9000;
		
		# With php fpm:
		fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	}

	# deny access to .htaccess files, if Apache's document root
	# concurs with nginx's one
	location ~ /\.ht {
		deny all;
	}
	
	# special folder handling, since .htaccess files are not supported
	
	# REST API
	
	location /restapi/v1 {
		rewrite ^(.+)/vtews/(.*)$ /restapi/v1/index.php/vtews/$2;
	}

    # Business Portal

    location /portal/v2 {
        rewrite ^\/portal\/v2\/(?!public)(.*)$ /portal/v2/public/$1;
    }
	
	# STORAGE
	
	location /storage {
		deny all;
		
		location /storage/uploads_emails_ {
			allow all;
		}
		
		location /storage/images_uploaded/ {
			allow all;
		}
		
		location ~* /storage/logo/.+\.(jpg|jpeg|png|gif)$ {
			allow all;
		}
		
		rewrite ^/storage/(.*)$ /getStorage.php?file=$1;
	}
	
	# PROTECTED FOLDERS
	
	location /logs {
		deny all;
	}
	
	location /plugins/dataimporter {
		deny all;
	}
	
	location /cache/sys {
		deny all;
	}
	
	location /cache/pdfmaker {
		deny all;
	}
	
	location /cache/import {
		deny all;
	}
	
	location /cache/session {
		deny all;
	}
	
	location /cache/pdf {
		deny all;
	}
	
	location /dataimport {
		deny all;
	}
	
	location /modules/VteSync/VteSyncLib/storage {
		deny all;
	}
	
	location /modules/Messages/src/attachment_tnef/plugins/attachment_tnef/class/ {
		deny all;
	}
	
	# SMARTOPTIMIZER
	
	# disabled by default, enable it if needed
	#location ~* \.(gif|jpe?g|png|swf|css|js|html?|xml|txt|ico)$ {
	#	rewrite ^(.*)$ /smartoptimizer/?$1;
	#}
}

Web Service Methods:

     
NameDescriptionParametersResponse
createCreate a record of the specified moduleelementType (String)element (Encoded)Return all fields and values of the created record
Ex:Url: VTE_URL/restapi/v1/vtews/createParameters:
{"elementType":"Accounts", "element":"{\"accountname\":\"account1\", \"assigned_user_id\":\"19x1\"}"}
updateUpdate the specified recordid (String)columns (Encoded)Return all fields and values of the updated record
Ex:Url: VTE_URL/restapi/v1/vtews/updateParameters:
{"id":"3x310", "columns":"{\"accountname\":\"test fede postman\"}"}
reviseUpdate the specified record. It’s different only for parameters, the result is the sameelement (Encoded)Return all fields and updated values
Ex:Url: VTE_URL//restapi/v1/vtews/reviseParameters: {"element":"{\"id\":\"3x27\",\"employees\":\"5\",\"industry\":\"Banking\"}"}
retrieveIllustrate the fields of the specified record and their relative valuesid (String)Return all fields and values of the specified record
Ex:Url: VTE_URL/restapi/v1/vtews/retrieveParameters:
{"id":"3x310"}
retrieveinventoryIllustrate the fields of the specified inventory record, their relative values and the product block’s informationid (String)Return all fields and values of the specified record and product’s block information
Ex:Url: VTE_URL//restapi/v1/vtews/retrieveinventoryParameters: {"id":"16x104"}
deleteDelete the specified recordid (String)Return the request status (successful or not)
Ex:Url: VTE_URL//restapi/v1/vtews/deleteParameters:
{"id":"3x306"}
queryExecute a query and return the result’s rowsquery (String)Return all rows of the executed query
Ex:Url: VTE_URL//restapi/v1/vtews/queryParameters: {"query":"SELECT * FROM Accounts WHERE accountname like '%vte%';"}
listtypesDescribe each one module which contains uitype of the specified formatfieldTypeList (Encoded)Return module information of the specified fieldtypes
Ex:Url: VTE_URL//restapi/v1/vtews/listtypesParameters:{"fieldTypeList":"[\"integer\",\"file\"]"}
describeDescribe the specified module and their relative fieldselementType (String)Return all module information and its fields properties(no hidden fields)
Ex:Url: VTE_URL//restapi/v1/vtews/describeParameters: {"elementType":"Accounts"}
describeallThe describeall method is different from describe one because it shows hidden fields tooElementType (Encoded)Return all module information and its fields properties(hidden fields too)
Ex:Url: VTE_URL//restapi/v1/vtews/describeallParameters: {"elementType":"Accounts"}
getlabelsReturn all labels and translated ones of the specified module,languageusername (String)language (String)module (String)Return labels and translated ones of the specified module, language
Ex:Url: VTE_URL//restapi/v1/vtews/getlabelsParameters: {"username":"admin", "language":"it_it", "module":"Accounts"}
getlangsReturn all languages installed into the CRM Return all CRM languages
loginpwdReturn user webservice access key if username and password are validusername (String)password (String)Return user webservice access key

Ex:Url: VTE_URL//restapi/v1/vtews/loginpwdParameters: {"username":"admin","password":"123456789"}
getmenulistReturn all modules information (visibility, tabid, name, sequence, ...) Return modules information and properties
oldoqueryReturn records that contain the searched value into specified module’s fieldsmodule (String)search_fields (Encoded)search_value (String)Return some record basic information where searched value is contained into the specified module’s fields
Ex:Url: VTE_URL//restapi/v1/vtews/oldoqueryParameters: {"module":"Accounts", "search_fields":"[\"accountname\", \"website\"]", "search_value":"vtenext"}


Is possibile to register a new custom method with this SDK call:

SDK::setRestOperation($rest_name, $handler_path, $function_name, $parameters);

$rest_name: method name called by REST webservice
$handler_path: file path where the funtion is defined
$function_name: defined function name
$parameters: associative array with parameterName and parameterType

Example

SDK::setRestOperation('check_exists','modules/SDK/examples/RestApi/CustomRestApi.php','vtws_check_exists', array('id'=>'string'));