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 K2 Module is implemented with the plg_jbackend_k2 plugin. It provides functions related to K2 content construction kit for Joomla (items and categories). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=k2
resource=categories
rootid=<R> (optional)
endlevel=<E> (optional)

Example

<end-point>?action=get&module=k2&resource=categories&rootid=<R>&endlevel=<E>

Example (REST format)

<end-point>/get/k2/categories?rootid=<R>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<category description>",
            "parent": "<parent category id>"
        },
        ...
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<category description>",
            "parent": "<parent category id>"
        }
    ]
}

Notes

If rootid is specified, starts to get subcategories from the specified category id instead of the root category. If endlevel is specified, get categories and all subcategories up to the specified number of level, otherwise get all levels (default).

Get a category

Request parameters

action=get
module=k2
resource=categories
id=<N>

Example

<end-point>?action=get&module=k2&resource=categories&id=<N>

Example (REST format)

<end-point>/get/k2/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "name": "<category name>",
    "alias": "<category alias>",
    "description": "<category description>",
    "robots": "<meta robots>",
    "author": "<meta author>",
    "language": "<language code>",
    "parent": "<category id>"
}

Notes

Language can be "*" if any.

Get the list of items

Request parameters

action=get
module=k2
resource=items
cats=<C1,C2,...,CN> (optional)
subs=<0|1> (optional)
featured=<0|1|2> (optional)
limit=<L> (optional)
page=<P> (optional)
ordering=<field> (optional)

Example

<end-point>?action=get&module=k2&resource=items&cats=<C>&subs=1

Example (REST format)

<end-point>/get/k2/items?cats=<C>&limit=<L>&page=<P>

Response

{
    "status": "ok",
    "total": "<total items>",
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    items: [
        {
            "id": "<item id>",
            "title": "<item title>",
            "alias": "<item alias>",
            "content": "<item content>",
            "featured": "<featured>",
            "images": {
                "image": "<image URL>",
                "imageWidth": "<image width>",
                "image_caption": "<image caption>",
                "image_credits": "<image credits>",
                "imageXSmall": "<image extra small URL>",
                "imageSmall": "<image small URL>",
                "imageMedium": "<image medium URL>",
                "imageLarge": "<image large URL>",
                "imageXLarge": "<image extra large URL>"
            },
            "video": {
                "video": "<video URL>",
                "video_caption": "<video caption>",
                "video_credits": "<video credits>"
            },
        "language": "<item language>",
        "category_id": "<category id>",
        "category_name": "<category name>",
        "author": "<item author>",
        "created": "<item creation date>",
        "modified": "<item modification date>"
        },
        ...
        {
            ...
        }
    ]
}

Notes

Cats:
List of categories id to include

Subs:
0=Do not include sub categories (default), 1=Include sub categories

Featured:
0=Hide, 1=Show (default), 2=Show only featured items

Ordering:
date, rdate, alpha, ralpha, order, rorder, featured, hits, rand, best, modified, publishUp, id (default)

Created and modified date format is YYYY-MM-DD HH:MM:SS

Get an item

Request parameters

action=get
module=k2
resource=items
id=<N>

Example

<end-point>?action=get&module=k2&resource=items&id=<N>

Example (REST format)

<end-point>/get/k2/items/<N>

Response

{
    "status": "ok",
    "id": "<item id>",
    "title": "<item title>",
    "alias": "<item alias>",
    "content": "<item content>",
    "featured": "<featured>",
    "images": {
        "image": "<image URL>",
        "imageWidth": "<image width>",
        "image_caption": "<image caption>",
        "image_credits": "<image credits>",
        "imageXSmall": "<image extra small URL>",
        "imageSmall": "<image small URL>",
        "imageMedium": "<image medium URL>",
        "imageLarge": "<image large URL>",
        "imageXLarge": "<image extra large URL>"
    },
    "video": {
        "video": "<video URL>",
        "video_caption": "<video caption>",
        "video_credits": "<video credits>"
    },
    "metadesc": "<meta description>",
    "metakey": "<meta keywords>",
    "metadata": {
        "robots": "<meta robots>",
        "author": "<meta author>",
        "rights": "<meta content rights>",
        "xreference": "<meta external reference>"
    },
    "language": "<language code>",
    "category_id": "<category id>",
    "category_name": "<category name>",
    "author": "<item author>",
    "created": "<item creation date>",
    "modified": "<item modification date>"
}

Notes

Created and modified date format is YYYY-MM-DD HH:MM:SS

Language can be "*" if any.

Plugin Settings

The following options are available for user plugin:

The SobiPro Module is implemented with the plg_jbackend_sobipro plugin. It provides functions related to SobiPro directory extension (sections, categories and entries). Here is the list of supported methods.

Get the list of sections

Request parameters

action=get
module=sobipro
resource=sections

Example

<end-point>?action=get&module=sobipro&resource=sections

Example (REST format)

<end-point>/get/sobipro/sections

Response

{
    "status": "ok",
    "total": <T>,
    "sections": [
        {
            "id": "<section id>",
            "nid": "<section nid>",
            "name": "<section name>"
        },
        ...
        {
            "id": "<section id>",
            "nid": "<section nid>",
            "name": "<section name>"
        }
]}

Get a section

Request parameters

action=get
module=sobipro
resource=sections
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=sections&id=<N>

Example (REST format)

<end-point>/get/sobipro/sections/<N>

Response

{
    "status": "ok",
    "id": "<section id>",
    "nid": "<section nid>",
    "name": "<section name>",
    "description": "<section description>",
    "owner": "<section owner id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>"
}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

Get the list of categories

Request parameters

action=get
module=sobipro
resource=categories
parent=<N>

Example

<end-point>?action=get&module=sobipro&resource=categories&parent=<N>

Example (REST format)

<end-point>/get/sobipro/categories?parent=<N>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "nid": "<category nid>",
            "name": "<category name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        },
        ...
        {
            "id": "<category id>",
            "nid": "<category nid>",
            "name": "<category name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

Get a category

Request parameters

action=get
module=sobipro
resource=categories
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=categories&id=<N>

Example (REST format)

<end-point>/get/sobipro/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "nid": "<category nid>",
    "name": "<category name>",
    "description": "<category description>",
    "owner": "<category owner id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>",
    "parent": "<parent id>"
}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

Get the list of entries

Request parameters

action=get
module=sobipro
resource=entries
category=<C>

Example

<end-point>?action=get&module=sobipro&resource=entries&category=<C>

Example (REST format)

<end-point>/get/sobipro/entries?category=<C>

Response

{
    "status": "ok",
    "total": <T>,
    "entries": [
        {
            "id": "<entry id>",
            "nid": "<entry nid>",
            "name": "<entry name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        },
        ...
        {
            "id": "<entry id>",
            "nid": "<entry nid>",
            "name": "<entry name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

Get an entry

Request parameters

action=get
module=sobipro
resource=entries
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=entries&id=<N>

Example (REST format)

<end-point>/get/sobipro/entries/<N>

Response

{
    "status": "ok",
    "id": "<entry id>",
    "nid": "<entry nid>",
    "name": "<entry name>",
    "owner": "<entry owner id>",
    "section": "<entry section id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>",
    "fields": [
        {
            "name": "<field name>",
            "fid": "<field id>",
            "nid": "<field nid>",
            "sid": "<field sid>",
            "section": "<section id>",
            "lang": "<language code>",
            "_data": "<field data>",
            "_rawData": "<field raw data>",
            "fieldType": "<field type>",
            "isFree": "<is free>",
            "position": "<position>"
        },
        ...
        {
            "name": "<field name>",
            "fid": "<field id>",
            "nid": "<field nid>",
            "sid": "<field sid>",
            "section": "<section id>",
            "lang": "<language code>",
            "_data": "<field data>",
            "_rawData": "<field raw data>",
            "fieldType": "<field type>",
            "isFree": "<is free>",
            "position": "<position>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

Plugin Settings

The following options are available for user plugin: