DGS API Mode

If mode is set to api, the XML will support RESTful.

<?xml version="1.0" encoding="UTF-8" ?>
<table name="currencies"
       charset="UTF-8"
       primaryKey="id"
       defaultOrderField="id"
       defaultOrderDirection="ASC"
       mode="api"
       rowsForPage="100" >
       <fields>
            <field type="text"
                   caption="<?php echo __('Code'); ?>"
                   name="ident"
                   width="50%" />
            <field type="text"
                   caption="<?php echo __('Name'); ?>"
                   name="name"
                   width="50%" />
       </fields>
       <actions>
            <action type="insert"
                    caption="<?php echo __('Add')?>"
                    title="<?php  echo __('Add'); ?>" />
            <action type="list" 
                    caption="<?php echo __('Currencies')?>" />
            <action type="edit"
                    caption="<?php echo __('Edit')?>"
                    title="<?php echo __('Edit'); ?>" />
            <action type="remove" 
                    caption="<?php echo __('Remove')?>" />
            <action type="info" 
                    caption="<?php echo __('Info')?>" /> 
       </actions>
</table>   

To retrieve all data, send a GET request to /festi/[XML_NAME]/[PLUGIN_NAME]/ or another custom URL.

To get (or delete) data for a single record, send a GET (DELETE) request with an additional GET parameter: [XML_NAME]%5BID%5D=12345.

To add a record to the table, send a POST request with JSON-formatted data in the message body. For example: {"name":"USD","ident":"USD"}.

To edit a record, send a PUT request with a GET parameter (same as for retrieving data) and JSON-formatted data in the message body.

  • GET: http://DOMAIN_NAME/festi/XML_NAME/PLUGIN_NAME/ - List Action
  • PUT: http://DOMAIN_NAME/festi/XML_NAME/PLUGIN_NAME/?XML_NAME[ID]=1 - Info Action
  • POST: http://DOMAIN_NAME/festi/XML_NAME/PLUGIN_NAME/ - Insert Action
  • PUT: http://DOMAIN_NAME/festi/XML_NAME/PLUGIN_NAME/?XML_NAME[ID]=1 - Edit Action
  • DELETE: http://DOMAIN_NAME/festi/XML_NAME/PLUGIN_NAME/?XML_NAME[ID]=1 - Remove Action

In API mode the edit, info and remove actions work on the row the request names without the conditions a request of a browser has (see Which row an action accepts): an API client has no list page and no parent row of a page. The API of a project has to decide itself which rows a client may reach, for example with IRowPermissionListener.

Using Remote RESTful API

You can use API to work with DGS.

Proxy Attribute

By default, SQL proxy is used to work with the database.

To work with a remote API, you need to:

  1. Define your Proxy class by inheriting from OpenApiProxy
  2. Add it to the attribute proxy="YourProxy"
  3. Add the required method getBaseEndpointUrl
  4. Override the methods needed to ensure compatibility with the remote API, for example: getHeaders, getListValuesRows, etc. You can see the list in OpenApiProxy

Example of working with GitLab API

Add DGS to work with Projects through GitLab API.

class GitLabApiProxy extends OpenApiProxy
{
    function getBaseEndpointUrl(...$params): string
    {
        return 'https://gitlab.varteq.com/api/v4/';
    }

    protected function getHeaders(string $storeName): array
    {
        return [
            'PRIVATE-TOKEN: '.$this->getAccessToken(),
            'Content-type: application/json'
        ];
    }

    protected function getAccessToken()
    {
        return 'XXXXXXX';
    }

    protected function isListValuesTotalInHeaders(): bool
    {
        return true;
    }

    public function getListValuesTotalFromHeaders(array $headers): int
    {
        if (array_key_exists('x-total', $headers) && !empty($headers['x-total'][0])) {
            return (int) $headers['x-total'][0];
        }

        return 0;
    }

    protected function appendListValuesLimitRequestParam(array &$params, array $limit): void
    {
        $params['page'] = $this->store->getCurrentPageIndex();
        $params['per_page'] = $limit['rowsPerPage'];
    }

    protected function appendListValuesOrderByRequestParam(array &$params, array $orderBy): void
    {
        $params['order_by'] = $orderBy['orderBy'];
        $params['sort'] = $orderBy['orderByDirection'];
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<table charset="UTF-8"
        name="projects"
        primaryKey="id"
        defaultOrderField="id"
        defaultOrderDirection="DESC"
        proxy="GitLabApi"
        rowsForPage="50">
    <fields>
        <field  type="readonly"
                name="id"
                required="true"
                sorting="true"
                caption="<?php echo __('ID'); ?>" />

        <field  type="text"
                name="name"
                required="true"
                caption="<?php echo __('Name'); ?>"
                sorting="true"
                filter="text" />

        <field  type="text"
                name="name_with_namespace"
                caption="<?php echo __('Namespace'); ?>"
                onlyList="true" />

        <field  type="datetime"
                name="created_at"
                isnull="true"
                caption="<?php echo __('Created at'); ?>"
                onlyList="true"
                sorting="true" />

        <field  type="checkbox"
                name="issues_enabled"
                isnull="true"
                onlyList="true"
                caption="<?php echo __('Issues Enabled'); ?>" />

        <field type="foreignKey"
            name="creator_id"
            isnull="true"
            foreignTable="users"
            foreignKeyField="id"
            foreignValueField="name"
            onlyList="true"
            caption="<?php echo __('Author'); ?>" />

    </fields>
    <actions>
        <action type="list"
            caption="<?php echo __('Projects'); ?>"/>
        <action type="insert"
            caption="<?php echo __('Add'); ?>"/>
        <action type="edit"
            caption="<?php echo __('Edit'); ?>"/>
        <action type="info"
            caption="<?php echo __('Info'); ?>"/>
        <action type="remove"
            caption="<?php echo __('Delete'); ?>"/>
    </actions>
</table>