Version 4.5.0

applications/downloads/api/categories.php

@@ -12,7 +12,7 @@
 namespace IPS\downloads\api;
 
 /* To prevent PHP errors (extending class does not exist) revealing path */
-if ( !defined( '\IPS\SUITE_UNIQUE_KEY' ) )
+if ( !\defined( '\IPS\SUITE_UNIQUE_KEY' ) )
 {
 	header( ( isset( $_SERVER['SERVER_PROTOCOL'] ) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0' ) . ' 403 Forbidden' );
 	exit;
@@ -29,9 +29,13 @@ class _categories extends \IPS\Node\Api\NodeController
 	protected $class = 'IPS\downloads\Category';
 
 	/**
-	 * GET /downloads/category
+	 * GET /downloads/categories
 	 * Get list of categories
 	 *
+	 * @apiparam	int		clubs			0|1 Include club categories, default: 1
+	 * @apiparam	int		page			Page number
+	 * @apiparam	int		perPage			Number of results per page - defaults to 25
+	 * @note		For requests using an OAuth Access Token for a particular member, only categories the authorized user can view will be included
 	 * @return		\IPS\Api\PaginatedResponse<IPS\downloads\Category>
 	 */
 	public function GETindex()
@@ -41,11 +45,10 @@ class _categories extends \IPS\Node\Api\NodeController
 	}
 
 	/**
-	 * GET /downloads/category/{id}
+	 * GET /downloads/categories/{id}
 	 * Get specific category
 	 *
 	 * @param		int		$id			ID Number
-	 *
 	 * @return		\IPS\Api\PaginatedResponse<IPS\downloads\Category>
 	 */
 	public function GETitem( $id )
@@ -55,12 +58,12 @@ class _categories extends \IPS\Node\Api\NodeController
 	}
 
 	/**
-	 * POST /downloads/category
+	 * POST /downloads/categories
 	 * Create a category
 	 *
 	 * @apiparam	int|null	parent					The ID number of the parent the category should be created in. NULL for root.
 	 * @apiparam	int			moderation				Files must be approved?
-	 * @apiparam	int			moderation_edits		New versions must be re-approved?
+	 * @apiparam	int			moderation_edits		New versions must be approved?
 	 * @apiparam	int			allowss					Allow screenshots?
 	 * @apiparam	int			reqss					Require screenshots?
 	 * @apiparam	int			comments				Allow comments?
@@ -68,21 +71,27 @@ class _categories extends \IPS\Node\Api\NodeController
 	 * @apiparam	int			reviews					Allow reviews?
 	 * @apiparam	int			reviews_mod				Reviews must be approved?
 	 * @apiparam	int			reviews_download		Files must be downloaded before a review can be left?
-	 *
+	 * @apiparam	object		permissions			An object with the keys as permission options (view, read, add, download, reply, review) and values as permissions to use (which may be * to grant access to all groups, or an array of group IDs to permit access to)
 	 * @return		\IPS\downloads\Category
+	 * @throws		1D365/2	NO_TITLE	A title for the category must be supplied
 	 */
 	public function POSTindex()
 	{
+		if ( !\IPS\Request::i()->title )
+		{
+			throw new \IPS\Api\Exception( 'NO_TITLE', '1D365/2', 400 );
+		}
+
 		return new \IPS\Api\Response( 201, $this->_create()->apiOutput( $this->member ) );
 	}
 
 	/**
-	 * POST /downloads/category/{id}
+	 * POST /downloads/categories/{id}
 	 * Edit a category
 	 * 
 	 * @apiparam	int|null	parent					The ID number of the parent the category should be created in. NULL for root.
 	 * @apiparam	int			moderation				Files must be approved?
-	 * @apiparam	int			moderation_edits		New versions must be re-approved?
+	 * @apiparam	int			moderation_edits		New versions must be approved?
 	 * @apiparam	int			allowss					Allow screenshots?
 	 * @apiparam	int			reqss					Require screenshots?
 	 * @apiparam	int			comments				Allow comments?
@@ -90,7 +99,8 @@ class _categories extends \IPS\Node\Api\NodeController
 	 * @apiparam	int			reviews					Allow reviews?
 	 * @apiparam	int			reviews_mod				Reviews must be approved?
 	 * @apiparam	int			reviews_download		Files must be downloaded before a review can be left?
-	 *
+	 * @apiparam	object		permissions			An object with the keys as permission options (view, read, add, download, reply, review) and values as permissions to use (which may be * to grant access to all groups, or an array of group IDs to permit access to)
+	 * @param		int		$id			ID Number
 	 * @return		\IPS\downloads\Category
 	 */
 	public function POSTitem( $id )
@@ -98,19 +108,23 @@ class _categories extends \IPS\Node\Api\NodeController
 		$class = $this->class;
 		$category = $class::load( $id );
 		
-		return new \IPS\Api\Response( 201, $this->_createOrUpdate( $category )->apiOutput( $this->member ) );
+		return new \IPS\Api\Response( 200, $this->_createOrUpdate( $category )->apiOutput( $this->member ) );
 	}
 
 	/**
-	 * DELETE /downloads/category/{id}
+	 * DELETE /downloads/categories/{id}
 	 * Delete a category
 	 *
-	 * @param		int		$id			ID Number
+	 * @param		int			$id							ID Number
+	 * @apiparam	int			deleteChildrenOrMove		The ID number of the new parent or -1 to delete all child nodes.
 	 * @return		void
+	 * @throws	1S359/1	INVALID_ID		The node ID does not exist
+	 * @throws	1S359/2	INVALID_TARGET	The target node cannot be deleted because the new parent node does not exist
+	 * @throws	1S359/3	HAS_CHILDREN	The target node cannot be deleted because it has children (pass deleteChildrenOrMove in the request to specify how to handle the children)
 	 */
 	public function DELETEitem( $id )
 	{
-		return $this->_delete( $id );
+		return $this->_delete( $id, \IPS\Request::i()->deleteChildrenOrMove ?? NULL );
 	}
 
 	/**
@@ -121,11 +135,6 @@ class _categories extends \IPS\Node\Api\NodeController
 	 */
 	protected function _createOrUpdate( \IPS\node\Model $category )
 	{
-		if ( !\IPS\Request::i()->title )
-		{
-			throw new \IPS\Api\Exception( 'NO_TITLE', '', 400 );
-		}
-
 		foreach ( array( 'title' => "downloads_category_{$category->id}", 'description' => "downloads_category_{$category->id}_desc" ) as $fieldKey => $langKey )
 		{
 			if ( isset( \IPS\Request::i()->$fieldKey ) )