This post will show how it can be simple to create an hybrid mobile app using HTML, CCS and Javascript (i.e. a Phonegap app), and jBackend to access to Joomla content in JSON format and so to use Joomla as data source to feed the app. It's easy as 1,2,3.

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 Content Module is implemented with the plg_jbackend_content plugin. It provides functions related to Joomla content (articles and categories). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=content
resource=categories
rootid=<R> (optional)
recursive=<true or 1> (optional)
countitems=<true or 1> (optional)

Example

<end-point>?action=get&module=content&resource=categories&rootid=<R>&recursive=<false>&countitems=<0>

Example (REST format)

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

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "title": "<category title>",
            "description": "<category description>",
            "parent_id": "<parent category id>",
            "numitems": <items count>
        },
        ...
        {
            "id": "<category id>",
            "title": "<category title>",
            "description": "<category description>",
            "parent_id": "<parent category id>",
            "numitems": <items count>
        }
    ]
}

Notes

If rootid is specified, starts to get subcategories from the specified category id instead of the root category. If recursive is true or 1, get categories and all subcategories, otherwise get only one level (default). If countitems is true or 1, return the number of articles of each category, otherwise do not return this information (default). Category id can be "root" for root node.

Get a category

Request parameters

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

Example

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

Example (REST format)

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

Response

{
    "status": "ok",
    "id": "<category id>",
    "title": "<category title>",
    "alias": "<category alias>",
    "description": "<category description>",
    "metadesc": "<meta description>",
    "metakey": "<meta keywords>",
    "metadata": {
        "page_title": "<meta title>",
        "author": "<meta author>",
        "robots": "<meta robots>"
    },
    "language": "<language code>",
    "parent_id": "<category id>",
    "level": "<category level>",
    "numitems": "<N>"
}

Notes

Language can be "*" if any. Category id can be "root" for root node.

Get the list of articles

Request parameters

action=get
module=content
resource=articles
catid=<C> (optional)
maxsubs=<S> (optional)
featured=<F> (optional)
limit=<L> (optional)
offset=<O> (optional)
orderby=<field> (optional)
orderdir=<dir> (optional)

Example

<end-point>?action=get&module=content&resource=articles&catid=<C>&maxsubs=<S>&featured=<F>&orderby=<id>

Example (REST format)

<end-point>/get/content/articles?catid=<C>&limit=<L>&offset=<O>

Response

{
    "status": "ok",
    "total": <total articles>,
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    "pages_current": <current page>,
    "pages_total": <total pages>,
    "articles": [
        {
            "id": "<article id>",
            "title": "<article title>",
            "alias": "<article alias>",
            "featured": "<featured>",
            "content": "<article content>",
            "catid": "<article category id>",
            "images": {
                "image_intro": "<image_url_for_intro>",
                "float_intro": "<float_side_for_intro>",
                "image_intro_alt": "<alt_text_for_intro>",
                "image_intro_caption": "<caption_for_intro>",
                "image_fulltext": "<image_url_for_fulltext>",
                "float_fulltext": "<float_side_for_fulltext>",
                "image_fulltext_alt": "<alt_text_for_fulltext>",
                "image_fulltext_caption": "<caption_for_fulltext>"
            },
            "tags": [
                {
                    "id": "<tag id>",
                    "title": "<tag title>",
                    "alias": "<tag alias>",
                    "language": "<tag language>"
                },
                ...
            ],
            "fields": [
                {
                    "id": "<field id>",
                    "title": "<field title>",
                    "name": "<field name>",
                    "type": "<field type>",
                    "default_value": "<default value>",
                    "group_id": "<field group id>",
                    "label": "<field label>",
                    "description": "<field description>",
                    "required": "<field required>",
                    "value": "<field value>",
                    "rawvalue": "<field raw value>"
                },
                ...
            ],
            "metakey": "<meta keywords>",
            "metadesc": "<meta description>",
            "metadata": {
                "robots": "<meta robots>",
                "author": "<meta author>",
                "rights": "<meta content rights>",
                "xreference": "<meta external reference>"
            },
            "language": "<language code>",
            "category_title": "<category title>",
            "category_alias": "<category alias>",
            "author": "<article author>",
            "created_date": "<created date>",
            "modified_date": "<modified date>",
            "published_date": "<publish up date>",
            "unpublished_date": "<publish down date>",
            "state": "<article state>"
            },
            ...
            {
                ...
            }
    ]
}

Notes

State:

• Published = 1,
• Unpublished = 0,
• Archived = 2,
• Trashed = -2

Max subs:
Number of subcategories to include (default 0=none)

Featured:
hide,only,show (default)

Order by:
id, title, alias, catid, state, created, created_by, ordering (default), hits

Order dir:
asc (default), desc

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

Property content is present only if plugin's option Content in article list is set.

Property tags is present only if plugin's option Add tags in article list is set.

Property fields is present only if plugin's option Prepare content in article list is set.

Get an article

Request parameters

action=get
module=content
resource=articles
id=<N>

Example

<end-point>?action=get&module=content&resource=articles&id=<N>

Example (REST format)

<end-point>/get/content/articles/<N>

Response

{
    "status": "ok",
    "id": "<article id>",
    "title": "<article title>",
    "alias": "<article alias>",
    "featured": "<featured>",
    "introtext": "<article intro text>",
    "content": "<article content>",
    "content_raw": "<article content raw>",
    "catid": "<article category id>",
    "images": {
        "image_intro": "<image_url_for_intro>",
        "float_intro": "<float_side_for_intro>",
        "image_intro_alt": "<alt_text_for_intro>",
        "image_intro_caption": "<caption_for_intro>",
        "image_fulltext": "<image_url_for_fulltext>",
        "float_fulltext": "<float_side_for_fulltext>",
        "image_fulltext_alt": "<alt_text_for_fulltext>",
        "image_fulltext_caption": "<caption_for_fulltext>"
    },
    "tags": [
        {
            "id": "<tag id>",
            "title": "<tag title>",
            "alias": "<tag alias>",
            "language": "<tag language>"
        },
        ...
    ],
    "associations": [
    ],
    "event": {
        "afterDisplayTitle": "<after display title>",
        "beforeDisplayContent": "<before display content>",
        "afterDisplayContent": "<after display content>"
    },
    "fields": [
        {
            "id": "<field id>",
            "title": "<field title>",
            "name": "<field name>",
            "type": "<field type>",
            "default_value": "<default value>",
            "group_id": "<field group id>",
            "label": "<field label>",
            "description": "<field description>",
            "required": "<field required>",
            "value": "<field value>",
            "rawvalue": "<field raw value>"
        },
        ...
    ],
    "cck_fields": [
    ],
    "metakey": "<meta keywords>",
    "metadesc": "<meta description>",
    "metadata": {
        "robots": "<meta robots>",
        "author": "<meta author>",
        "rights": "<meta content rights>",
        "xreference": "<meta external reference>"
    },
    "language": "<language code>",
    "category_title": "<category title>",
    "category_alias": "<category alias>",
    "author": "<article author>",
    "parent_id": "<parent id>",
    "parent_title": "<parent title>",
    "parent_alias": "<parent alias>",
    "parent_route": "<parent route>",
    "created_date": "<created date>",
    "modified_date": "<modified date>",
    "published_date": "<publish up date>",
    "unpublished_date": "<publish down date>",
    "version": "<article version>",
    "hits": "<article hits>",
    "rating": "<article rating>",
    "rating_count": "<article rating count>",
    "state": "<article state>"
}

Notes

State:

• Published = 1,
• Unpublished = 0,
• Archived = 2,
• Trashed = -2

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

Language can be "*" if any.

Property content_raw is present only if plugin's option Include content raw is set.

Property event is present only if plugin's option Show article event is set.

Property cck_fields is present only if plugin's option Include CCK is set.

Get the list of articles by tag id

Request parameters

action=get
module=content
resource=tagarticles
tagid=<T1,T2,...,Tn>
limit=<L> (optional)
offset=<O> (optional)

Example

<end-point>?action=get&module=content&resource=tagarticles&tagid=<T>&limit=<L>&offset=<O>

Example (REST format)

<end-point>/get/content/tagarticles?tagid=<T>&limit=<L>&offset=<O>

Response

{
    "status": "ok",
    "total": <total articles>,
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    "pages_current": <current page>,
    "pages_total": <total pages>,
    articles: [
        {
            "id": "<article id>",
            "title": "<article title>",
            "alias": "<article alias>",
            "featured": "<featured>",
            "content": "<article content>",
            "images": {
                "image_intro": "<image_url_for_intro>",
                "float_intro": "<float_side_for_intro>",
                "image_intro_alt": "<alt_text_for_intro>",
                "image_intro_caption": "<caption_for_intro>",
                "image_fulltext": "<image_url_for_fulltext>",
                "float_fulltext": "<float_side_for_fulltext>",
                "image_fulltext_alt": "<alt_text_for_fulltext>",
                "image_fulltext_caption": "<caption_for_fulltext>"
            },
            "tags": [
                {
                    "id": "<tag id>",
                    "title": "<tag title>",
                    "alias": "<tag alias>",
                    "language": "<tag language>"
                },
                ...
            ],
            "metadesc": "<meta description>",
            "metakey": "<meta keywords>",
            "metadata": {
                "robots": "<meta robots>",
                "author": "<meta author>",
                "rights": "<meta content rights>",
                "xreference": "<meta external reference>"
            },
        "category_title": "<category title>",
        "author": "<article author>",
        "published_date": "<article date>"
        },
        ...
        {
            ...
        }
    ]
}

Notes

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

Get an article by alias

Request parameters

action=get
module=content
resource=articlebyalias
id=<alias>

Example

<end-point>?action=get&module=content&resource=articlebyalias&id=<alias>

Example (REST format)

<end-point>/get/content/articlebyalias/<alias>

Response

Same response as "Get an article"

Notes

Same notes as "Get an article".

Plugin Settings

The following options are available for user plugin:

The User Module is implemented with the plg_jbackend_user plugin. It provides functions related to Joomla users and ACL. Here is the list of supported methods.

User login

Request parameters

action=post
module=user
resource=login
username=<username>
password=<password>

Example

<end-point>?action=post&module=user&resource=login&username=<username>&password=<password>

Example (REST format)

<end-point>/post/user/login?username=<username>&password=<password>

Response

{
    "status": "ok",
    "userid": <userid>,
    "username": "<username>",
    "session_id": "<session_id>"
}

User logout

Request parameters

action=get
module=user
resource=logout

Example

<end-point>?action=get&module=user&resource=logout

Example (REST format)

<end-point>/get/user/logout

Response

{
    "status": "ok"
}

User registration

Request parameters

action=post
module=user
resource=register
username=<username>
password=<password>
email=<email>
firstname=<firstname>
lastname=<lastname>

Example

<end-point>?action=post&module=user&resource=register&username=<username>&password=<password>&email=<email>&firstname=<firstname>&lastname=<lastname>

Example (REST format)

<end-point>/post/user/register?username=<username>&password=<password>&email=<email>&firstname=<firstname>&lastname=<lastname>

Response

{
    "status": "ok"
}

User remind

Sends an email to the user's account with a password remind link.

Request parameters

action=get
module=user
resource=remind
email=<email>

Example

<end-point>?action=get&module=user&resource=remind

Example (REST format)

<end-point>/get/user/remind

Response

{
    "status": "ok"
}

User reset

Sends an email to the user's account with a password reset link.

Request parameters

action=get
module=user
resource=reset
email=<email>

Example

<end-point>?action=get&module=user&resource=reset

Example (REST format)

<end-point>/get/user/reset

Response

{
    "status": "ok"
}

User profile

Request parameters

action=get
module=user
resource=profile

Example

<end-point>?action=get&module=user&resource=profile

Example (REST format)

<end-point>/get/user/profile

Response

{
    "status": "ok",
    "fields": [
        {
            "id": "<id>",
            "title": "<title>",
            "name": "<name>",
            "language": "<language>",
            "type": "<type>",
            "default_value": "<default value>",
            "context": "<context>",
            "group_id": "<group id>",
            "label": "<label>",
            "description": "<description>",
            "required": "<required>",
            "language_title": "<language title>",
            "language_image": "<language image>",
            "group_title": "<group title>",
            "value": "<value>",
            "rawvalue": "<raw value>"
        },
        ...
    ],
    "_errors": [<_errors>],
    "groups": {
        "<groupid>": "<groupid>"
        ...
    },
    "id": "<id>",
    "name": "<name>",
    "username": "<username>",
    "email": "<email>",
    "block": "<block>",
    "sendEmail": "<sendEmail>",
    "registerDate": "<registerDate>",
    "lastvisitDate": "<lastvisitDate>",
    "activation": "<activation>",
    "params": {
        "admin_style": "<admin_style>",
        "admin_language": "<admin_language>",
        "language": "<language>",
        "editor": "<editor>",
        "helpsite": "<helpsite>",
        "timezone": "<timezone>"
    },
    "lastResetTime": "<lastResetTime>",
    "resetCount": "<resetCount>",
    "otpKey": "<otpKey>",
    "otep": "<otep>",
    "requireReset": "<requireReset>",
    "tags": {
        "typeAlias": <typeAlias>,
        "tags": "<tags>"
    }
}

User profile update

Allows to update the user profile (user must be authenticated). The requests must use the POST method with a JSON payload.

Request parameters

action=put
module=user
resource=profile

Example

POST <end-point>?action=put&module=user&resource=profile

Example (REST format)

POST <end-point>/put/user/profile

JSON payload data:

{
    "name": "<name>",
    "username": "<username>",
    "password": "<password>",
    "email": "<email>",
    "profile": {
        "city": "<city>"
        ...
    },
    "com_fields": {
        "field-1": "<value 1>",
        "field-2": "<value 2>"
        ...
    }
}

Response

{
    "status": "ok"
}

User status

Allows to check the current status of the user (guest or logged in), and provides some additional information.

Request parameters

action=get
module=user
resource=status

Example

<end-point>?action=get&module=user&resource=status

Example (REST format)

<end-point>/get/user/status

Response

{
    "status": "ok",
    "is_guest": <0 or 1>,
    "user_id": "<user_id>",
    "session_id": "<session_id>",
    "session_expire": <session_expire>
}

Plugin Settings

The following options are available for user plugin:

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"}

Once an end-point is published the web clients can start to make HTTP requests and consume services provided by jBackend API. It is possible to test if all is working as expected using any REST client that allows to build custom HTTP requests (much better if the client supports JSON decode to better show server responses). Some good clients are available as browser plugin for both Firefox and Chrome. We suggest REST Easy for Firefox and Postman - REST Client for Chrome.

Let's assume the end-point menu item can be accessed with the following URL:

http://www.mysite.com/index.php/jbackend

Calling just the URL without any parameter we will get the following JSON response:

{
    "status": "ko",
    "error_code": "REQ_MNS",
    "error_description": "Module not specified"
}

Note that the HTTP Response Code is always 200 even in case of errors. The error condition is reported by the "status" value (ok, ko). Additional information about the error can be found in the "error_code" and the "error_description" values.

To check jBackend features it is available a sandbox with the last version of jbackend and all modules installed, and free access type on the end-point. To play with the sandbox a Postman collection is available to download here:

http://www.selfget.com/downloads/file/41-jbackapp-postman-collection.html

It needs only to be imported into Postman and is ready to play.

Push Notifications

jBackend includes a fully featured platform for sending Push Notifications over Google GCM (Android) and Apple APNs (iOS). Moreover, it supports multiple mobile applications, and you can manage them all from a single Joomla installation.

The component interface includes functions to manage Apps, Devices and Notifications, and there's a Push module to interact with jBackend from the outside (e.g. to send registration token from your app or start the push notification sending process).

The first thing to do just after installation is to enable jBackend basic plugins. To do this go to menu "Extensions" -> "Plug-in Manager", and filter plugin list for type "jbackend".

Each one of these plugins has some configurable options, so it is enough to click on "Status" buttons to enable the plugins, but it is necessary to edit a plugin to change its settings.

Note that when a plugin is disabled the API functions it provides will NOT be available.

To start using jBackend it is a good practice to publish an "end-point". This is a Joomla menu item which provides a defined URL to access to jBackend APIs (the one associated with the menu link), and can be configured as needed using menu item's options. To create an end-point go to "Menus" -> "Menu Manager", click on the menu that will contain the end-point (or create a new menu, like an hidden menu) and add a new menu item.

Select a menu type "jBackend" -> "Request" and set the "Access type" in the "Options" tab, and other options available for the current endpoint.

The following options are available for each endpoint:

Currently jBackend supports the following access type:

Note that APIs could be accessed without to publish any end-point, just calling the jBackend component with http://<siteurl>/index.php?option=com_jbackend&<params> (default requests). For this reasons there are global options defined as default and used for such situations. These general options can be accessed by the "Options" button in the jBackend panel. For security reasons the default access is set to "API Key".

The following global options are available:

REST format

If Joomla SEF is enabled, the endpoint can serve requests with the REST format (e.g. /get/content/articles/<N>).

jBackend is a Joomla extension that introduces a set of APIs for access to all Joomla's content and features, and easily integrate any Joomla site with any external system. It extends the power of Joomla allowing you to use your site as a "backend system" to serve and feed any kind of client (mobile apps, news channels, affiliate sites, and any other external system).

jBackend also provides a full push notifications platform for iOS and Android mobile apps. It is possible to manage multiple apps, to register devices for each app, and to schedule push notifications sending on registered devices, filtered by app and platform type.

jBackend is designed to be "extensible" via plugins. Adding new plugins means to add new APIs to support new Joomla extensions. The basic package already includes three plugins, the User Module (that supports Joomla users and ACL), the Content Module (for the standard Joomla content, categories and articles), and the Push Module (to work with push notifications). New plugins are on the way, to add support for the most used Joomla extensions (e.g. K2, Zoo, VirtueMart, HikaShop, and so on). Additional plugins can be installed separately, so you can install and use only the necessary modules, and keep your CMS lightweight and efficient.

jBackend access is possible through an "end-point", that can be published like a menu item. It is possible to publish several end-points and configure access rules separately for each one. The access can be free, or restricted with a standard user login or through the use of an API Key. API Keys can be generated and configured (e.g. in terms of limitations like expiration or daily access) in jBackend panel. This allows full control on API access provided to clients.

It is possible to enable requests tracking for each endpoint separately. In this way all requests received from the endpoint are stored in the database and can be used for security audit or for statistical analysis.

It is also possible to enable specific modules for each endpoint separately. This increase the control level on the pool of functions or services to expose for each endpoint.

End-point channels can be accessed through HTTP, requests can be compliant to RESTful pattern, and responses are JSON encoded. In the future is expected to support the ability to provide XML responses.

jBackend basic extension has just one package to download and install. The package includes the component and three plugins (User Module, Content Module, and Push Module), and support the installation with "upgrade" mode, so there’s no need to uninstall any previous installed version.

To install jBackend, login to Joomla backend as administrator, and go to menu "Extension Manager". Click the browse button, select the package file (jBackendX.X_J3.zip) and click the installation button.

The package will be uploaded on the server and then installed. After installation finished a message will report a successful message.

That’s all. Now we are ready to start using jBackend.

Upgrade procedure

When upgrading from a previous version of jBackend, there is no need to first uninstall the old package. As mentioned earlier, jBackend supports the "upgrade" mode for the installation, so is enough to just install the new package over the old one. The component and the three plugins included in the basic package will be upgraded.

Note that during the upgrade also the database tables are upgraded when needed, but without to delete or loose any table data. It is in charge of the installation process to upgrade tables structure if needed. All the data (e.g. API Keys) will be preserved.