Joomla API JSON template

From Netdesign Wiki
Revision as of 23:15, 4 July 2015 by Fabiobuda (Talk | contribs) (Alternatives to Joomla API JSON template)

Jump to: navigation, search

Introduction

Joomla API JSON template by Netdesign is not a Joomla Component nor a complete RESTful CRUD API service for Joomla.

Joomla API JSON template is far more different from existing Joomla - paid and free - API components and supports only reading operations.

If you need a simple, fast and read-only solution to integrate your Joomla website with another website or with a mobile app, Joomla API JSON template could be the right choice. If you need a CRUD (Create, Read, Update, Delete) API you can't benefit from Joomla API template package and should choose from some alternatives (go to #Alternatives_to_Joomla_API_JSON_template).

Details

The first difference between Joomla API template and existing alternatives is in the type of package: Joomla API is a template and not a component nor a plugin. The second difference is that you can expose all data you want from your Joomla instance using the desired Joomla modules, YES! it may sound strange but you can use and configure the desired (and supported) Joomla modules.

Joomla API template is designed to avoid the decoupling between business logics and presentation layer. Generally this is a bad solution but we discovered some advantages using this approach. The first advantage is the simple customization.

Why decoupling?

Please get a comfortable setting before start reading this paragraph, you need to be very outstretched to follow this argument and avoid railing against me.

Let start!

Any software engineer would say you that loose coupling is a big advantage in software design because you are able to have many autonomous systems wich interoperate to reach your goals. In the three-tier architecture, for example, you have three independant blocks: data layer, business logic and presentation layer working togheter to make your application work.

When you decouple pieces of software you have the big advantage of maintainability, scalability, reusability ed interoperability following the ancient latin expression divide et impera that means: breaking up larger concentrations of power into pieces that individually have less power than the one implementing the strategy.

When you decouple pieces of software you decouple basically the implementation of your software requirements specification finding the solution that best fits your problem (many real-world problems are solved by design patterns, if you haven't done yet take a look at the book Design Patterns: Elements of Reusable Object-Oriented Software).

Joomla implements an MVC (Model, View, Controller) design pattern following the right way to do its job: making web developers and web designers forget data structure and logics focusing only on their job: build a Joomla html template (that represents ultimately the presentation layer of your website).

So when the web developer writes lines of PHP and HTML where logics hide themselves?

The logics are implemented in the Controller so you don't care if the webmaster wants the category homeopathy ordered by title or by creation time, it will be the controller to read all user preferences just stored in the backend and pass to your template the correct filtered and ordered data.

So why don't reuse the included parts of Joomla business logic in your JSON Joomla API? It could seems a blasphemy, I know, but it is really an interesting approach.

Really, how does it work?

Joomla JSON template API works as an HTML template with the difference that it returns JSON encoded data. This means that you can use custom modules in custom positions to generate custom API results in your endpoints.

Joomla JSON API doesn't ask your client to make standard API requests such as GET /component/article/$id or GET /component/category, it asks it to query all APIs like a user navigate link by link through your pages starting from the Homepage.

A clear example - data layout

In the source code below you can see the default index.php of our Joomla JSON API template discovering how is simple to customize all data returned to clients:

    <?php
         $isThisHomepage = JUri::getInstance()->toString() == JUri::base()."?template=api";
         
         $d = JFactory::getDocument();
         $d->setMimeEncoding('application/json');
         require_once dirname(__FILE__).'/libs/ApiObjectFactory.php';
    ?>
    <?php
    if( $isThisHomepage ){
    ?>
        {
          "latest": <jdoc:include type="modules" name="apilatest" />,
          "topmenu": <jdoc:include type="module" name="mod_menu" title="Menu Principale" />,
          "tagspopular": <jdoc:include type="module" name="mod_tags_popular" title="(API) Tag popolari Home" />
        }
    <?php
    } else {
    ?>
        {
            "content": <jdoc:include type="component" />
            "contextual": <jdoc:include type="modules" name="apicontextualmenu" />
        }
    <?php
    }
    ?>

The source code above uses two different data-layout, the first for the API root (homepage) and the second for all other endpoints (components). The first data-layout returns latest articles from mod_articles_category, topmenu from mod_menu and tagspopular from mod_tags_popular while the second data-layout returns content from component and contextual from mod_menu.

This way if the webmaster wants to show 5, 10 or 15 articles in latest it could set it in the mod_articles_category configuration interface and your API client will get the same amount of articles.

An homepage API data layout example

The image below illustrates an example of homepage HTML template and its coupling with the JSON template data-layout:

Illustrazione.svg.png

Your HTML template will include modules (such as Top Menù, Home Latest Articles) and the component from the Joomla core. In the same way your JSON data-layout will use the same modules and components to return structured JSON data about your website.

This way, getting with the client the homepage of your Joomla website you will have all data you needs to integrate in another website or in a mobile application.

A component API data layout example

Illustrazione-2.svg.png

Technical Documentation

Features

Our Joomla JSON API template does:

  • Observe the backend configuration such as items per page, filters and items order in components and modules
  • Include the support for the search component (experimental)
  • Work as a standard HTML template making you able to use <jdoc /> statements
  • Return the urlfull of every object (Article, Category, Tag, Menu Item) observing the SEF configuration making you able to link to the correct path
  • Return the apiurlfull of every object (Article, Category, Tag, Menu Item) making you able to request child items directly without building any query URL

How to use the Joomla JSON API

To use our Joomla JSON API template you have to download it and install inside your joomla instance as you do for all templates. Once installed you should modify the index.php configuring all data-layout you want.

See the next paragraphs to know all supported Joomla modules and components, then you will be able to use <jdoc /> statements to output all desired JSON structured data.

NOTE: Remember that all your requests have to specify the template you want to use:

   http://your.joomlasite.com/?template=joomlaapitemplate

How to configure a data-layout

As seen before a data-layout is the main configuration of your API. It resides in the index.php of the template and appears as a JSON object containing the JSON representation of your <jdoc> statements:

    <?php
         $isThisHomepage = JUri::getInstance()->toString() == JUri::base()."?template=api";
         
         $d = JFactory::getDocument();
         $d->setMimeEncoding('application/json');
         require_once dirname(__FILE__).'/libs/ApiObjectFactory.php';
    ?>
    <?php
    if( $isThisHomepage ){
    ?>
        {
          "latest": <jdoc:include type="modules" name="apilatest" />,
          "mainCategories": <jdoc:include type="module" name="mod_menu" title="Main categories" />,
          "secondaryCategories": <jdoc:include type="module" name="mod_menu" title="Secondary categories" />,
          "help": <jdoc:include type="module" name="mod_menu" title="Help" />,
          "tagspopular": <jdoc:include type="module" name="mod_tags_popular" title="(API) Tag popolari Home" />
        }
    <?php
    } else {
    ?>
        {
            "content": <jdoc:include type="component" />
            "contextual": <jdoc:include type="modules" name="apicontextualmenu" />
        }
    <?php
    }
    ?>

In this example any single <jdoc> statement represents a JSON object or a list of objects. This way you are able to customize the data returned to the client.

How to go deep in the datasource

Every returned item (be it a category, an article, a tag or a menu item) has two fundamental attributes: urlfull and apiurlfull. The urlfull attribute is the SEF-aligned URL of the resource whereas the apiurlfull attribute is the SEF-aligned URL of the resource with the ?template=joomlaapitemplate querystring in addition.

When you get your homepage you will be able to reach all contents following the apiurlfull of every item.

Supported components

  • com_content.article
  • com_content.category
  • com_tags.tag
  • com_search

Supported modules

  • mod_articles_category
  • mod_menu
  • mod_tags_popular

Downloads

Download and install the latest Joomla API JSON Template package:

NOTES: Version 1.0.3 is not reported to work but should work fine on Joomla 2.5+

Alternatives to Joomla API JSON template

If you are yet in doubt about using Joomla API JSON template you should consider all available alternatives to get structured data from your website:

  • jBackend - Limited online documentation & full support only for content and user [1], paid download [2]
  • com_api - Lacks of documentation [3], the open source package seems to work only with Techjoomla Reportoise or JTicketing Event Manager IOS & Android Apps

Licence

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.