18.10 REST Webservice

REST Webservice Settings

From the CRM settings its possible to view the available web services (referred here as webservice, or REST webservice), to allow external applications to interact with the CRM itself, using the REST paradigm. A webservice is accessible by an URL address (referred here as endpoint), usually made by the URL address of the vte installation, followed by /restapi/v1/vtews/, and the method name associated to the endpoint of interest.

Once configured, it is possible to invoke the desired endpoint with HTTP requests to execute the requested actions.

HTTP requests format

HTTP requests support the POST method only and the Basic authentication type, meaning the definition of Authorization defined as Basic <credentials>, where <credentials> is the Base64 encoding of the user name and the accesskey, separated by :.

Webservice requests are intended to return a response in JSON format: on success they return a status and the data computed by the endpoint, and on error they return the error code and relative description.

User selector and access keys, list of modules and fields views

By using the picklist associated to User Name, it is possible to select the user, and this allows, with related buttons, to view the accesskeys and the available modules to do HTTP request with the selected user.

The button associated with Webservice access key allows to view, after entering of one's own password, the access keys generated by the user: those are used to authorize webservices requests, as noted in the paragraph HTTP requests format. Note that to add more access keys, the user needs to enter in their preference page, and go to the section Webservices, REST Api Configuration: refer to the section dedicated in the user preferences page.

The button associated with Modules and fields usable allows to view the list of the modules available to the user and their internal name, to use in the webservice requests where needed.

REST Documentation Page (OpenAPI)

By clicking the button associated with Display REST Documentation, it is possible to display the page which lists the endpoints exposed by the CRM. Initially empty, click on Generate OpenAPI Documentation to get the definition of the endpoints that will be used for their layout.

It is then possible to test single endpoints by clicking the button Test Request, located in the example box adjacent to the description of the method, for the desired endpoint and user. The user can be selected with the related selector, located centrally at the top of the page.

Configurazione Web service esterni per utilizzo nei processi

Nella pagina delle impostazioni è possibile aggiungere client web service esterni, basati su Zapier (si rimanda al capitolo dedicato), o impostazioni personalizzate.

Una volta configurati e attivati, tramite il pulsante Aggiungi Client Webservice, possono essere visionati nella sezione Lista webservice client configurati, e utilizzati nei processi.