Skip to content

Changes

Page history
Create API Designer authored by Vikas's avatar Vikas
Hide whitespace changes
Inline Side-by-side
API-Designer.md 0 → 100644
View page @ 03474aea
## API Designer {#api-designer}
API Designer provides a workbench for developers to develop HTTP based APIs which can be exposed to the VTAP runtime or the external application for integration easily.
APIs can be defined using VADL specification. APIs access needs user authorization and follows standard record access configuration made within CRM.
### VADL Specification {#vadl-specification}
Vtiger Application Definition Language (VADL) is based on XML syntax to enable administrators or developers to be able to define API without needing deep programming skills.
```
<?xml version="1.0" ?>
<api method="post">
<!-- definition goes here -->
</api>
```
VADL allows you to
* Define APIs
* CURD (Create, Retrieve, Update, Delete) on entity modules.
* Invoke HTTP based (REST / SOAP) endpoint through (GET/POST/PUT/DELETE) methods
* With Authentication (Basic / Bearer token based)
* Accept request parameters and bind as API inputs.
* Bind API inputs to VTAP runtime configuration store.
### API Endpoint {#api-endpoint}
API defined through API Designer can be access through the [restapi](https://help.vtiger.com/article/147111249-Rest-API-Manual) endpoint as follows:
[https://vtigercrm.instance.url/restapi/v1/apidesigner/api/APINAME](https://vtigercrm.instance.url/restapi/v1/apidesigner/api/APINAME)
HTTP Basic Authentication (username and accesskey) should be used and HTTP Method is controlled within API definition.
### API Samples {#api-samples}
#### Select Records {#select-records}
To select (firstname, lastname) record fields of Module for matching email (=[[email protected]](mailto:[email protected])) the API definition would be:
```
<?xml version="1.0" ?>
<api method="get">
<select module="Contacts">
<record>
<field name="firstname"> </field>
<field name="lastname"> </field>
</record>
<where>
<field name="email" value="[email protected]"> </field>
</where>
</select>
</api>
```
#### Select Records With Value Binding {#select-records-with-value-binding}
To select (firstname, lastname) of Contacts record where email field value matching incoming request parameter email_address
```
<?xml version="1.0" ?>
<api method="get">
<select module="Contacts">
<record>
<field name="firstname"> </field>
<field name="lastname"> </field>
</record>
<where>
<field name="email" value="@email_address"> </field>
</where>
</select>
</api>
```
#### Create Record {#create-record}
If the intent is to create Contacts module record by accepting (firstname, lastname, email) from the request parameter and respond back with record id then API definition for the same would be as shown below.
```
<?xml version="1.0" ?>
<api method="post">
<create module="Contacts">
<record>
<field name="firstname" value="@firstname"></field>
<field name="lastname" value="@lastname"></field>
<field name="email" value="@email"></field>
</record>
<return>
<field name="id"></field>
</return>
</create>
</api>
```
#### Create Record WIth Reference Field {#create-record-with-reference-field}
Reference field rules can have a combination of select and create rules which gives the ability to create reference records if select does not yield any match.
```
<?xml version="1.0" ?>
<api method="post">
<create module="Potentials">
<record>
<field name="potentialname" value="@name"></field>
<field name="amount" value="@amount"></field>
<field name="contact_id" module="Contacts">
<select>
<where>
<field name="email" value="@email"></field>
</where>
</select>
<create>
<record>
<field name="lastname" value="@lastname"></field>
<field name="firstname" value="@firstname"></field>
<field name="email" value="@email"></field>
<field name="contacttype" value="Lead"></field>
</record>
</create>
</field>
</record>
</create>
</api>
```
#### Update Record {#update-record}
To replace email field value with incoming parameter (new_email) on all Contacts record matching incoming parameter (old_email) and respond back with record ID of changed records.
```
<?xml version="1.0" ?>
<api method="put">
<update module="Contacts">
<record>
<field name="email" value="@new_email"></field>
</record>
<return>
<field name="id"></field>
</return>
<where>
<field name="email" condition="eq" value="@old_email"></field>
</where>
</update>
</api>
```
#### Upsert
```
<api method="post" module="Contacts">
<upsert>
<where>
<field name="id" condition="eq" value="@CRMID"></field>
</where>
<update>
<record>
<field name="email" value="@email" presence="optional" ></field>
</record>
</update>
<create>
<record>
<field name="firstname" value="@firstname" presence="optional" ></field>
<field name="lastname" value="@lastname" presence="optional" ></field>
<field name="email" value="@email" presence="optional" ></field>
</record>
</create>
<return>
<field name="id"></field>
</return>
</upsert>
</api">
```
#### Invoke HTTP Rest API {#invoke-http-rest-api}
Using bearer token invoke Google Sheet API
```
<?xml version="1.0" ?>
<api method="get">
<rest>
<url>https://sheets.googleapis.com/v4/spreadsheets/sheetID</url>
<auth>
<bearer token="@token" />
</auth>
</rest>
</api>
```
#### REST URL Builder {#rest-url-builder}
Rest API URL can be composed with dynamic value binding by passing arguments in the url node.
To construct URL of the form
[https://sheets.googleapis.com/v4/spreadsheets/${sheet_id}/values/Sheet1!A1:append?valueInputOption=RAW](https://sheets.googleapis.com/v4/spreadsheets/${sheet_id}/values/Sheet1!A1:append?valueInputOption=RAW)
Where ${sheet_id} needs dynamic binding from the request parameter followed by the static part.
You can achieve by following url rules.
```
<url
SHEETID="@sheetid" OPTIONS="values/Sheet1!A1:append?valueInputOption=RAW">
https://sheets.googleapis.com/v4/spreadsheets/$SHEETID/$OPTIONS</url>
```
#### OAuth Support {#oauth-support}
VTAP server end handles the OAuth2 flow and lets you focus on getting the user authentication for access data of the desired application.
To make API requests with such OAuth2 credentials you need to cite (type, service and module) on the oauth rule definition.
<table>
<tr>
<td>type
</td>
<td>vtap
</td>
<td>
</td>
</tr>
<tr>
<td>service
</td>
<td>Target service to connect via OAuth2
</td>
<td>Google, Facebook etc..
</td>
</tr>
<tr>
<td>module
</td>
<td>CRM Module which owns the OAuth2 grant
</td>
<td>
</td>
</tr>
</table>
Example:
```
<?xml version="1.0" ?>
<api method="post">
<rest method="post">
<url SHEETID="@sheetid" OPTIONS="values/Sheet1!A1:append?valueInputOption=RAW">https://sheets.googleapis.com/v4/spreadsheets/$SHEETID/$OPTIONS</url>
<auth>
<oauth type="vtap" service="Google" module="CUSTOM_MODULE"> </oauth>
</auth>
<parameters raw-post-data="true">
<parameter name='values' value='@row_data' presence="optional"></parameter>
</parameters>
</rest>
</api>
```
#### Special Value Binding {#special-value-binding}
<table>
<tr>
<td>$login.{$user_field_name}
</td>
<td>Logged in user object field value
<p>
$user_field_name can be:
<ul>
<li>user_name
<li>email1
</li>
</ul>
</td>
</tr>
<tr>
<td>$vtapoauth.{$SERVICE}{$EXT_MODULE_NAME}
</td>
<td>To bind bearer token VTAP has been acquired for the SERVICE and MODULE_NAME already.
<p>
Example: $vtapoauth.Google.vtcmsheetview
</td>
</tr>
<tr>
<td>$apps.$user.{$key}
</td>
<td>data stored in vtap user data store
</td>
</tr>
<tr>
<td>$apps.$app.{$key}
</td>
<td>data stored in vtap app store
</td>
</tr>
<tr>
<td>$apps.$prefs.{$key}
</td>
<td>data stored in vtap preferences store
</td>
</tr>
</table>
\ No newline at end of file