Issue #89 feat: Category plugin enhancements (#90)

* Issue #89 feat: Category plugin enhancements - Update get single category api - Update get category list api * Issue #89 feat: Fix return types
techjoomla · Jan 10, 2019 · 2d69766 · 2d69766
1 parent 927d3dd
commit 2d69766
Show file tree

Hide file tree

Showing 5 changed files with 307 additions and 170 deletions.
diff --git a/categories/README.md b/categories/README.md
@@ -1,51 +1,57 @@
 API to create and get Joomla categories
 
-## Create / Update Category
+## Get Single Category
 
 ```http
-POST /index.php?option=com_api&app=categories&resource=categories&format=raw
+GET /index.php?option=com_api&app=categories&resource=category&format=raw&id=:id
 ```
-OR update an existing category
+
+Alternatively, you can call this API as follow (assuming you have created a menu with alias as 'api' for com_api)
+
 ```http
-POST /index.php?option=com_api&app=categories&resource=categories&format=raw&id=:id
+GET /api/categories/category/:id
 ```
 
 #### Request Params
 
-| Param Name | Required | Type | Comment  |
-| ---------- | -------- | ------- | :---- |
-| title      | YES      | STRING |         |
-| alias      | NO      | STRING | URL alias. Will be generated based on title if kept empty |
-| description    | NO      | STRING |        |
-| published    | NO      | INT | 1 = Published (Default) / 0 = Unpublished |
-| parent_id      | NO      | INT |  Specify a parent category id if you wish to create a subcategory |
-| language | NO | STRING | Will use the site's default language if none provided. |
-| extension | YES | STRING | Since Joomla supports using the categories extension for 3rd party components, this field specifies the extension name. Use com_content for article categories.  |
-| access | NO | INT | Access Level for Category |
+| Param Name | Required | Comment |
+| ---------- | -------- | :------ |
+| fields         | NO       | Defaults to id, title, created_time |
 
 
 #### Response Params
 
-| Param Name | Comment |
-| ---------- | :------ |
-| success | true if the category was created, false if there was a problem |
+| Param Name | Comment  |
+| ---------- | :------- |
+| success | true if the API call succeeds, false if there was a problem |
 | message | Error mesage in case success is false |
 | data.results | Array containing a single [Category Object](#category-object) in case of success. Empty array in case of failure. |
 
 ## Get Categories List
+
 ```http
 GET /index.php?option=com_api&app=categories&resource=categories&format=raw
 ```
+
+Alternatively, you can call this API as follow (assuming you have created a menu with alias as 'api' for com_api)
+
+```http
+GET /api/categories/categories
+```
+
 #### Request Params
 
 | Param Name | Required | Comment |
 | ---------- | -------- | :------ |
-| limit         | NO       | Defaults to 20        | 
-| limitstart      | NO      | Defaults to 0        |
-| filters | NO | Key value pairs of values to filter on |
-| search | NO | search key for searching category titles |
-| fields         | NO       | Defaults to id, title, created_time | 
-
+| limit      | NO       | Defaults to 20        |
+| limitstart | NO       | Defaults to 0        |
+| search     | NO       | search key for searching category titles |
+| filters[access]    | NO       | Access level |
+| filters[extension] | NO       | Defaults to 'com_content'        |
+| filters[language]  | NO       | eg: hi-IN for Hindi |
+| filters[level]     | NO       | eg: 1 for top level |
+| filters[published] | NO       | 1 / 0, defaults to 1 |
+| fields (not implemented yet)     | NO       | Defaults to id, title, created_time |
 
 #### Response Params
 
@@ -55,28 +61,38 @@ GET /index.php?option=com_api&app=categories&resource=categories&format=raw
 | message | Error mesage in case success is false |
 | data.results | Array of [Category Objects](#category-object) in case of success. Empty array in case of failure. |
 
+## Create / Update Category
 
-## Get Single Category
 ```http
-GET /index.php?option=com_api&app=categories&resource=categories&format=raw&id=:id
+POST /index.php?option=com_api&app=categories&resource=categories&format=raw
+```
+OR update an existing category
+```http
+POST /index.php?option=com_api&app=categories&resource=categories&format=raw&id=:id
 ```
 
 #### Request Params
 
-| Param Name | Required | Comment |
-| ---------- | -------- | :------ |
-| fields         | NO       | Defaults to id, title, created_time | 
+| Param Name | Required | Type | Comment  |
+| ---------- | -------- | ------- | :---- |
+| title      | YES      | STRING |         |
+| alias      | NO      | STRING | URL alias. Will be generated based on title if kept empty |
+| description    | NO      | STRING |        |
+| published    | NO      | INT | 1 = Published (Default) / 0 = Unpublished |
+| parent_id      | NO      | INT |  Specify a parent category id if you wish to create a subcategory |
+| language | NO | STRING | Will use the site's default language if none provided. |
+| extension | YES | STRING | Since Joomla supports using the categories extension for 3rd party components, this field specifies the extension name. Use com_content for article categories.  |
+| access | NO | INT | Access Level for Category |
 
 
 #### Response Params
 
-| Param Name | Comment  |
-| ---------- | :------- |
-| success | true if the API call succeeds, false if there was a problem |
+| Param Name | Comment |
+| ---------- | :------ |
+| success | true if the category was created, false if there was a problem |
 | message | Error mesage in case success is false |
 | data.results | Array containing a single [Category Object](#category-object) in case of success. Empty array in case of failure. |
 
-
 ## Category Object
 The actual contents of the category object will vary based on which fields are requested, however the below is the list of all possible fields.
 

diff --git a/categories/categories.php b/categories/categories.php
@@ -1,21 +1,36 @@
 <?php
 /**
- * @package API plugins
- * @copyright Copyright (C) 2009 2014 Techjoomla, Tekdi Technologies Pvt. Ltd. All rights reserved.
- * @license GNU GPLv2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
- * @link http://www.techjoomla.com
-*/
+ * @package     API
+ * @subpackage  com_api
+ *
+ * @author      Techjoomla <[email protected]>
+ * @copyright   Copyright (C) 2009 - 2019 Techjoomla, Tekdi Technologies Pvt. Ltd. All rights reserved.
+ * @license     GNU GPLv2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
+ */
 
-defined('_JEXEC') or die( 'Restricted access' );
+// No direct access.
+defined('_JEXEC') or die('Restricted access');
 
-jimport('joomla.plugin.plugin');
-
-class plgAPICategories extends ApiPlugin
+/**
+ * Category API plugin class
+ *
+ * @package  API
+ * @since    1.6.0
+ */
+class PlgAPICategories extends ApiPlugin
 {
+	/**
+	 * Constructor.
+	 *
+	 * @param   object  &$subject  The object to observe.
+	 * @param   array   $config    An optional associative array of configuration settings.
+	 *
+	 * @since   1.6.0
+	 */
 	public function __construct(&$subject, $config = array())
 	{
 		parent::__construct($subject, $config = array());
 
-		ApiResource::addIncludePath(dirname(__FILE__).'/categories');
+		ApiResource::addIncludePath(dirname(__FILE__) . '/categories');
 	}
 }
diff --git a/categories/categories.xml b/categories/categories.xml
@@ -9,18 +9,17 @@
 	<copyright>Techjoomla. All rights reserved.</copyright>
 	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
 	<description>This plugin is for content Request</description>
-<files>
-	<filename plugin="categories">categories.php</filename>
+	<files>
+		<filename plugin="categories">categories.php</filename>
 		<folder>categories</folder>
-</files>
-<languages>
-	<language tag="en-GB">en-GB.plg_api_categories.ini</language>
-	<language tag="en-GB">en-GB.plg_api_categories.sys.ini</language>
-</languages>
+	</files>
+	<languages>
+		<language tag="en-GB">en-GB.plg_api_categories.ini</language>
+		<language tag="en-GB">en-GB.plg_api_categories.sys.ini</language>
+	</languages>
 	<config>
 		<fields name="params">
-			<fieldset name="basic">
-			</fieldset>
+			<fieldset name="basic" />
 		</fields>
 	</config>
 </extension>