The Release System Module is implemented with the plg_jbackend_release plugin. It provides functions to implement a full Joomla Update Server and/or a generic Package Distribution System based on Joomla. It supports both free and paid packages, and it is seamlessly integrated with Joomla user's groups for authorization and license key generation. Here is the list of supported methods.

Generate key by email

Sends an email to the user with the license key for the specified package group.

Request parameters

action=post
module=release
resource=keybyemail
id=<package group>
email=<user email>

Example

<end-point>?action=post&module=release&resource=keybyemail&id=redj_ent&email=This email address is being protected from spambots. You need JavaScript enabled to view it.

Example (REST format)

<end-point>/post/release/keybyemail/redj_ent?email=This email address is being protected from spambots. You need JavaScript enabled to view it.

Response

{
    "status": "ok"
}

Notes

email is the user's account email on Joomla.

Generate key by authentication

Returns the license key for the specified package group.

Request parameters

action=post
module=release
resource=keybyauth
id=<package group>
username=<username>
password=<password>

Example

<end-point>?action=post&module=release&resource=keybyauth&id=redj_ent&username=user123&password=pass123

Example (REST format)

<end-point>/post/release/keybyauth/redj_ent?username=user123&password=pass123

Response

{
    "status": "ok",
    "email": "user email",
    "key": "license key"
}

Notes

username and password are the credentials used for the user's account on Joomla.

Validate key

Checks if a license key is valid for the specified package group.

Request parameters

action=post
module=release
resource=validate
id=<package group>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=validate&id=redj_ent&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/validate/redj_ent?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

{
    "status": "ok"
}

Verify key

Checks if a license key is valid for the specified package id.

Request parameters

action=post
module=release
resource=verify
id=<package id>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=verify&id=redj_ent_190&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/verify/redj_ent_190?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

{
    "status": "ok"
}

Notes

This method is intended to verify a license key over a specific package id before to download it.

Download package

Download the package for the specified package id.

Request parameters

action=post
module=release
resource=download
id=<package id>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=download&id=redj_ent_190&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/verify/redj_ent_190?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

The binary package (as application/octet-stream)

Plugin Settings

The following options are available for release system plugin:

Version 3.8.0:

• Fixed an issue with create notifications for devices;
• [plg_jbackend_content] added function to get an article by alias;
• [plg_jbackend_content] dropped unpublished articles in get articles by tag;
• [plg_jbackend_user] fixed an issue with FieldsHelper;
• [plg_jbackend_push] replaced GCM with FCM.

Version 3.7.0:

• Added license integration with jBackend Release System.

Version 3.6.0:

• Fixed an issue with API key usage;
• Fixed an issue with session_id;
• Now all dates in DATETIME format are UTC-based;
• [plg_jbackend_content] output date format changed to ISO 8601;
• [plg_jbackend_content] added max limit option;
• [plg_jbackend_user] fixed profile extra fields.

Version 3.5.0:

• [plg_jbackend_content] extended support for joomla custom fields to the article list.

Version 3.4.0:

• Added the list of endpoints on the dashboard;
• [plg_jbackend_content] added support for joomla custom fields.

Version 3.3.0:

• Added a log of all notifications sent;
• Added target devices to push notifications;
• [plg_jbackend_push] fixed an issue with NOW;
• [plg_jbackend_content] fixed an issue with function to get articles by tags.

Version 3.2.0:

• Improved CORS support;
• Added delete all logs button;
• Added endpoint filtering to logs;
• Added target endpoints feature for API keys;
• Added the user information to a registered device;
• Added support for api_key passed as Authorization header (Authorization: api_key );
• Added support for api_key passed as JSON parameter;
• Added target users and groups to push notifications;
• [plg_jbackend_user] fixed an issue with registration, remind and reset when captcha is enabled;
• [plg_jbackend_user] added an option to process register, remind and reset as an authentication request;
• [plg_jbackend_content] added an option to return also raw content (no content plugin);
• [plg_jbackend_push] added an API function to create a push notification.

Version 3.1.0:

• Added support for session_id passed as GET/POST/JSON parameter;
• Added support for custom payload in push notifications;
• Fixed an issue with log search.

Version 3.0.0:

• Added support for push notifications for iOS and Android;
• Added user information to logs;
• Improved logs filtering;
• Added CSV export to logs;
• [plg_jbackend_content] added hits to single article response;
• [plg_jbackend_content] added an option to exclude content from article list;
• [plg_jbackend_content] added an option to include support for SEBLOD CCK custom fields;
• [plg_jbackend_user] added profile request;
• [plg_jbackend_user] added profile update request;
• [plg_jbackend_user] added status request.

Version 2.1.3:

• [plg_jbackend_user] fixed a PHP 5.3 compatibility issue (array initialization).

Version 2.1.2:

• Added basic CORS feature;
• [plg_jbackend_user] added username remind request;
• [plg_jbackend_user] added password reset request.

Version 2.1.1 (only for J3):

• Added the force SSL option.

Version 2.1.0:

• Fixed an issue with delete log entry;
• Fixed an issue with installer script;
• Added the ability to select which modules to enable for each endpoint.

Version 2.0.2:

• Fixed an issue with API key expiration check related to never expiring keys;
• [plg_jbackend_content] added filter by featured in the list of articles;
• [plg_jbackend_content] added featured field in the response for the list of articles;
• [plg_jbackend_content] added tags to response for articles (only for J3);
• [plg_jbackend_content] added tagarticles resource to get articles by tag (only for J3).

Version 2.0.1:

• Added onBeforeCheckModule event.

Version 2.0.0:

• Added a trace function for logs and statistics;
• Added a new dashboard as a better landing page;
• [plg_jbackend_content] fixed an issue with generateImagesFields() function;
• [plg_jbackend_content] added a plugin option to force full image URLs in content.

Version 1.0.3:

• [plg_jbackend_user] fixed an issue with com_users language costants.

Version 1.0.2:

• [plg_jbackend_content] fixed an issue with orderby and orderdir parameters;
• [plg_jbackend_content] added images fields for a single article and the list of articles;
• [plg_jbackend_content] added a plugin option to return relative or full URLs for images fields;
• [plg_jbackend_content] changed the date format of published date to YYYY-MM-DD HH:MM:SS.

Version 1.0.1:

• Completed porting to J2
• Some minor fixes and little improvements

Version 1.0.0:

• Initial J3 version

Menu module

Version 1.0.1:

• Fixed an issue with get menu items due to a new ACL check.

Version 1.0.0:

• Initial version.

K2 module

Version 1.3.1:

• Fixed an issue with ordering parameter in items.

Version 1.3.0:

• Added support for language filter on categories and items;
• Added an option to force full url for all img tags;
• Improved support for K2 plugins in the list of items.

Version 1.2.0:

• Added an option to include or exclude full content from items response;
• Added introtext to item and items response;
• Added extra_fields and extra_fields_search to item and items response;
• Added image field to category and categories response;
• Fixed an issue with items ordering.

Version 1.1.1:

• Fixed an issue with path of images.

Version 1.1.0 (only for J3):

• Fixed an issue with list of items.

Version 1.0.4 (only for J2):

• Fixed an issue with path of images.

Version 1.0.3:

• Some code optimization.

Version 1.0.2:

• Fixed name of plugin options constants;
• Changed error code K2_KGE to K2_CGE.

Version 1.0.1:

• Completed porting to J2;
• Some minor fixes and little improvements.

Version 1.0.0:

• Initial J3 version.

SobiPro module

Version 1.2.0:

• Added category_name filter field for entries;
• Added an option to enable JSON payload on entries action.

Version 1.1.0:

• Changed entries function to support multiple categories.

Version 1.0.1:

• Some code optimization.

Version 1.0.0:

• Initial version.

ZOO module

Version 1.1.1:

• Extended named elements also for a single item (thanks to Ray Lawlor).

Version 1.1.0:

• Added an option to include elements in the list of items (thanks to Ray Lawlor);
• Added an option to use slug (friendly) names for elements (thanks to Ray Lawlor).

Version 1.0.0:

• Initial version.

Kunena module

Version 1.0.0:

• Initial version.

Community Builder module

Version 1.0.1:

• Added full URL for avatar field in the get user profile.

Version 1.0.0:

• Initial version.

jBackend provides a robust and extensible solution to expose content and services through a Joomla website. The component provides the basic structure that has in charge of managing requests, controlling accesses, and dispatching incoming requests to the corresponding module. The jBackend architecture is extensible because its service modules are implemented as Joomla plugins, so adding new plugins allows to add new services and expose the contents of new extensions.

In this section we will describe how to create custom modules, and what is the structure of a jBackend plugin. For this purpose it was created an "Hello World" plugin available for download here:

http://www.selfget.com/downloads/file/31-plg-jbackend-helloworld-j30.html

Structure of supported requests

Each HTTP request to an jBackend endpoint MUST include at least three parameters:

action=<action_type>
module=<module_name>
resource=<service_request>

The action would specify one of the HTTP methods used in a RESTful service (e.g. GET, PUT, POST, or DELETE). This is because all Joomla requests are made using GET, so this FIRST parameter introduces the missing information.

The module parameter indicates the name of the module that has in charge of managing this request (e.g. content). This can be implemented as a single jBackend plugin, or even a pool of plugins where each one implements a subset of module services. As example, for com_content core extension a content plugin already exists, which provides read-only access to content and categories. It could be possible to create a new plugin (e.g. plg_jbackend_content_admin) registered also as content module, which takes in charge editor functions like create content and categories.

The resource parameter specifies the service we are requesting to the module (e.g. articles of the content module, login service of the user module, etc.). This parameter must be validated and managed by the plugin itself, no checks will be made on this by jBackend (it cannot know about services provided by each plugin).

Considering all the required parameters (action, module, and resource), each request has this structure:

<end-point>?action=<action_type>&module=<module_name>&resource=<service_request>

If Joomla SEF is enabled, the request can assume this REST-like structure:

<end-point>/<action_type>/<module_name>/<service_request>

A request can also take additional parameters needed by the resource itself for the required service (e.g. the id of the article). This parameters can be added as a standard URL query string, so the request structure assumes this aspect:

<end-point>?action=<action_type>&module=<module_name>&resource=<service_request>&var1=<value1>&...&varN=<valueN>

Or can be (when SEF is enabled):

<end-point>/<action_type>/<module_name>/<service_request>?var1=<value1>&...&varN=<valueN>

An event onBeforeCheckModule is triggered just before to check the module name to dispatch. This permits to override the module variable (as well as action and resource variables) before the request dispatching process and can be useful, as example, when a plugin must deal with existing client requests that cannot be customized as required by jBackend.

Using onBeforeCheckModule it is possible, as example, to match a request like the following:

<endpoint>?var=catchme

This request doesn't include any of the required variables (action, module, resource), but we can "catch" the var and set the required variables:

  public function onBeforeCheckModule()
  {
    $app = JFactory::getApplication();
    $var = $app->input->getString('var');
    if ($var === 'catchme') {
      $app->input->set('action', 'get');
      $app->input->set('module', 'content');
      $app->input->set('resource', 'articles');
      $app->input->set('catid', '64');
      $app->input->set('id', '71');
    }
  }

Basic elements of a jBackend plugin

As a standard Joomla plugin, any jBackend plugin needs an XML installation file with the following structure:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="jbackend" method="upgrade">
    <name>plg_jbackend_helloworld</name>
...
</extension>

The plugin group must be "jbackend". All other XML elements are the same of a standard Joomla plugin. The PHP plugin code should have a generateError() function which builds and return all plugin specific errors:

  /**
   * This is the function to generate plugin specific errors
   * The error response is an array with the following structure:
   *    array(
   *     'status' => 'ko',
   *     'error_code' => $errorCode,
   *     'error_description' => <short error description>
   *    )
   *
   * @param  string  $errorCode  The error code to generate
   *
   * @return  array  The response of type error to return
   */
  public static function generateError($errorCode)
  {
    $error = array();
    $error['status'] = 'ko';
    switch($errorCode) {
      case 'REQ_ANS':
        $error['error_code'] = 'REQ_ANS';
        $error['error_description'] = 'Action not specified';
        break;
      case 'HWD_GEN':
        $error['error_code'] = 'HWD_GEN';
        $error['error_description'] = 'Generic hello world error';
        break;
    }
    return $error;
  }

It is not mandatory, but a good practice for the format of the error code is to use a pattern like XXX_YYY, where XXX is a code associated to the plugin (e.g. HWD for the helloworld plugin), and YYY for the specific error (e.g. GEN for generic error).

The other function that any jBackend plugin should have is the onRequest<Module>() function. This is called by jBackend during requests dispatching process. It has three parameters, an input parameter $module that is the module name and is used by the plugin to understand if it should handle the request, an output parameter $response that is the response object, and a $status parameter that can return additional information. The function returns true if there are no problems (status = ok), false in case of errors (status = ko):

public function onRequestHelloWorld($module, &$response, &$status = null)

The first thing the onRequest function should do is to check if it must handle the request or not. If not, it should return to improve the performance of the dispatching process:

if ($module !== 'helloworld') return true; // Check if this is the triggered module or exit

The second thing is to add the plugin to the module call stack:

// Add to module call stack
jBackendHelper::moduleStack($status, 'helloworld'); // Add this request to the module stack register

After these tasks, it is possible to get request vars and process the response:

$app = JFactory::getApplication();
$action = $app->input->getString('action');
$resource = $app->input->getString('resource');

// Check if the action is specified
if (is_null($action)) {
  $response = plgJBackendHelloWorld::generateError('REQ_ANS'); // Action not specified
  return false;
}

switch ($resource)
{
  case 'greeting':
    if ($action == 'get')
    {
      return $this->actionGreeting($response, $status);
    }
    break;
  case 'about':
    if ($action == 'get')
    {
      return $this->actionAbout($response, $status);
    }
    break;
}

return true;

Each function like actionGreeting() and actionAbout() is specific to manage the resource requested by the action. To maintain the code clean it is a good practice to create a different function for each action.

The following is an example of an action() function that shows the code structure and how to manage the errors:

  public function actionGreeting(&$response, &$status = null)
  {
    $app = JFactory::getApplication();

    // Get additional request parameters
    $id = $app->input->getInt('id');
    if (!is_null($id))
    {
      // Example of how to generate and return an error inside an action function
      if ($id == '101')
      {
        $response = plgJBackendHelloWorld::generateError('HWD_GEN'); // Generic hello world error
        return false;
      }
    }

    // Get plugin params
    $option_name = $this->params->get('option_name', 0);

    $response['status'] = 'ok';
    $response['message'] = $this->_greeting_msg;
    if ($option_name)
    {
      $response['option'] = 'true';
    }
    return true;
  }

The general format for any error response is the following:

{
    "status": "ko",
    "error_code": "<code>",
    "error_description": "<description>"
}

The following table includes all error codes with description, grouped by "realm".

KNN_KNIKunena not installed{"status":"ko","error_code":"KNN_KNI","error_description":"Kunena not installed"}