Mobile API Design Guide

{
	"status": "success",
	"data": {
		"resource_name": "blog",
		"module_name": "blog",
		"title": "Et a dolor eum libero nostrum cumque.",
		"description": "Esse beatae voluptas officiis...",
		"module_id": "blog",
		"item_id": 0,
		"is_approved": true,
		"is_sponsor": false,
		"is_featured": false,
		"is_liked": false,
		"is_friend": false,
		"is_pending": false,
		"post_status": 1,
		"text": "Esse beatae voluptas officiis ratione ",
		"image": null,
		"statistic": {
			"total_like": 0,
			"total_comment": 0,
			"total_view": 1,
			"total_attachment": 0
		},
		"privacy": 0,
		"user": {
			"full_name": "Sheridan Hahn",
			"avatar": null,
			"id": 841
		},
		"categories": [
			{
				"id": 4,
				"name": "Family & Home",
				"subs": null
			},
			{
				"id": 9,
				"name": "Sports",
				"subs": null
			}
		],
		"tags": [
			{
				"tag_text": "tag me",
				"id": 3
			}
		],
		"attachments": [],
		"id": 1,
		"creation_date": "2016-06-21T04:53:48+00:00",
		"modification_date": null,
		"link": "http://localhost:7788/blog/1/et-a-dolor-eum-libero-nostrum-cumque/",
		"extra": {
			"can_view": true,
			"can_like": true,
			"can_share": true,
			"can_delete": true,
			"can_report": true,
			"can_add": true,
			"can_edit": true,
			"can_comment": true,
			"can_publish": false,
			"can_feature": true,
			"can_approve": false,
			"can_sponsor": true,
			"can_sponsor_in_feed": false,
			"can_purchase_sponsor": true
		},
		"self": null,
		"links": {
			"likes": {
				"ref": "mobile/like?item_type=blog&item_id=1"
			},
			"comments": {
				"ref": "mobile/comment?item_type=blog&item_id=1"
			}
		},
		"feed_param": {
			"item_id": 1,
			"comment_type_id": "blog",
			"total_comment": 0,
			"like_type_id": "blog",
			"total_like": 0,
			"feed_title": "Et a dolor eum libero nostrum cumque.",
			"feed_link": "http://localhost:7788/blog/1/et-a-dolor-eum-libero-nostrum-cumque/",
			"feed_is_liked": false,
			"feed_is_friend": false,
			"report_module": "blog"
		}
	},
	"error": null
}

<?php
// Fetch blog data from database then create blog resource
	$blog = \Phpfox::getService("blog")->get($blogId);
	$blogResource = new BlogResource($blog)

<?php

/* A lot of code above */
class PostResource extends ResourceBase
{
/* ... */
	protected function loadMetadataSchema(ResourceMetadata $metadata = null)
	{
		parent::loadMetadataSchema($metadata);
		$this->metadata
		    ->mapField('title', ['type' => ResourceMetadata::STRING])
		    ->mapField('description', ['type' => ResourceMetadata::STRING])
		    ->mapField('item_id', ['type' => ResourceMetadata::INTEGER])
		    ->mapField('module_id', ['type' => ResourceMetadata::STRING])
		    ->mapField('is_approved', ['type' => ResourceMetadata::BOOL])
		    ->mapField('is_sponsor', ['type' => ResourceMetadata::BOOL])
		    ->mapField('is_featured', ['type' => ResourceMetadata::BOOL])
		    ->mapField('is_liked', ['type' => ResourceMetadata::BOOL])
		    ->mapField('is_friend', ['type' => ResourceMetadata::BOOL])
		    ->mapField('post_status', ['type' => ResourceMetadata::INTEGER]);
	}
}

<?php
class PostApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
/.../
	public function __naming()
	{
		return [
		/* API route `/restful_api/mobile/post/search-form` will map with PostApi::searchForm() method */
			'post/search-form'=>[
				'get'=>'searchForm'
			],
		];
	}
}

<?php 

namespace Apps\Posts\Api\Resource; 
/* ... */ 
class PostResource extends ResourceBase
{
	/**
	Define the unique resource name
	*/
	const RESOURCE_NAME = "post"; 
	const TAG_CATEGORY = 'post';
	public $resource_name = self::RESOURCE_NAME;
	public $module_name = 'post'; 
	/**
	@var string Post's title mapping
	*/
	public $title; 
	/**
	@var string Post's description mapping
	*/
	public $description; 
	/**
	@var string Post's parent module id
	*/
	public $module_id; 
	/**
	@var int Post's parent id
	*/
	public $item_id; 
	/**
	@var bool Status of the post
	*/
	public $is_approved; 
	/**
	@var bool sponsor status of the post
	*/
	public $is_sponsor; 
	/**
	@var bool sponsor status of the post
	*/
	public $is_featured;
	public $is_liked;
	public $is_friend;
	public $post_status;
	public $text;

<?php

/* A lot of code above */
class PostResource extends ResourceBase
{
/* ... */
	protected function loadMetadataSchema(ResourceMetadata $metadata = null)
	{
		parent::loadMetadataSchema($metadata);
		$this->metadata
			->mapField('title', ['type' => ResourceMetadata::STRING])
			->mapField('description', ['type' => ResourceMetadata::STRING])
			->mapField('item_id', ['type' => ResourceMetadata::INTEGER])
			->mapField('module_id', ['type' => ResourceMetadata::STRING])
			->mapField('is_approved', ['type' => ResourceMetadata::BOOL])
			->mapField('is_sponsor', ['type' => ResourceMetadata::BOOL])
			->mapField('is_featured', ['type' => ResourceMetadata::BOOL])
			->mapField('is_liked', ['type' => ResourceMetadata::BOOL])
			->mapField('is_friend', ['type' => ResourceMetadata::BOOL])
			->mapField('post_status', ['type' => ResourceMetadata::INTEGER]);
	}
}

<?php 

/* A lot of code above */
class PostResource extends ResourceBase
{
/* ... */
/**
Get detail url
@return string
*/
	public function getLink()
	{
		return \Phpfox::permalink('post', $this->id, $this->title);
	} 
	public function getImage()
	{
		return Image::createFrom([
			'file' => $this->rawData['image_path'],
			'server_id' => $this->rawData['server_id'],
			'path' => 'post.url_photo',
			'suffix' => '_1024'
		]);
	} 

	public function getCategories()
	{
		return $this->categories;
	} 
	public function getTags()
	{
		return $this->tags;
	} 
	public function getText()
	{
		if (empty($this->text) && !empty($this->rawData['text'])) {
			$this->text = $this->rawData['text'];
		}
		TextFilter::pureHtml($this->text, true);
		return $this->text;
	}
    /* ... */
} 

<?php
namespace Apps\Posts\Service; 
/* ... */ 
class PostApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
	private $postService; 
	/**
	@var Process
	*/
	private $processService; 
	/**
	@var Category
	*/
	private $categoryService; 
	/**
	@var \User_Service_User
	*/
	private $userService; 

	public function __construct()
	{
		parent::__construct();
		$this->postService = Phpfox::getService("post");
		$this->categoryService = Phpfox::getService('post.category');
		$this->processService = Phpfox::getService('post.process');
		$this->userService = Phpfox::getService('user');
	}
    /* .. */
}

<?php 

namespace Apps\Posts\Service;
/* ... */ 
class PostApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
	/**
	 * Get list post
	 *
	 * @param array $params
	 * @return array|mixed
	 * @throws ValidationErrorException
	 */
	function findAll($params = [])
	{
	    /* ... */
		$aItems = $this->browse()->getRows();
		if ($aItems) {
			$this->processRows($aItems);
		} 
		return $this->success($aItems);
	} 
	
    /**
	 * @param $params
	 * @return array|bool
	 */
	function findOne($params)
	{
		$id = $this->resolver->resolveId($params);
		/* ... */
		return $this->success($resource->loadFeedParam()->toArray());
	} 

	public function delete($params)
	{
		$id = $this->resolver->resolveId($params); 
		$result = Phpfox::getService('post.process')->delete($id);
		if ($result !== false) {
			return $this->success([
				'id' => $id
			]);
		}
		return $this->error('Cannot delete post'); 
	} 
	
    /**
	 * Get Create/Update document form
	 * @param array $params
	 * @return mixed
	 * @throws \Exception
	 */
	public function form($params = [])
	{
		/** @var PostForm $form */
		$form = $this->createForm(PostForm::class, [
			'title' => 'adding_a_new_post',
			'method' => 'post',
			'action' => UrlUtility::makeApiUrl('post')
		]);
		/* ... */
		return $this->success($form->getFormStructure());
	} 
	/**
	 * Create a new Post API
	 * @param array $params
	 * @return array|bool|mixed
	 */
	public function create($params = [])
	{
	  /* ... */
	} 
	
    /**
	 * Update a post
	 *
	 * @param $params
	 * @return mixed
	 */
	public function update($params)
	{
	 /* ... */
	} 

	/**
	 * @param $id
	 * @param bool $returnResource
	 * @return array|PostResource
	 */
	function loadResourceById($id, $returnResource = false)
	{
		$item = Phpfox::getService("post")->getPost($id); 
		if (empty($item['post_id'])) {
			return null;
		}
		if ($returnResource) {
			return $this->processOne($item);
		}
		return $item;
	} 
	/**
	 * Update multiple document base on document query
	 *
	 * @param $params
	 * @return mixed
	 * @throws \Exception
	 */
	public function patchUpdate($params)
	{
		/* ... */
	} 


	/**
	 * Get for display on activity feed
	 * @param array $feed
	 * @param array $item detail data from database
	 * @return array
	 */
	public function getFeedDisplay($feed, $item)
	{
		/* ... */
	} 

	/**
	 * Create custom access control layer
	 */
	public function createAccessControl()
	{
		$this->accessControl = new PostAccessControl($this->getSetting(), $this->getUser()); 
		/* ... */
	} 
	
    /**
	 * @param array $params
	 * @return mixed
	 */
	function searchForm($params = [])
	{
		$this->denyAccessUnlessGranted(PostAccessControl::VIEW);
		/** @var PostSearchForm $form */
		$form = $this->createForm(PostSearchForm::class, [
			'title' =>'search',
			'method' => 'GET',
			'action' => UrlUtility::makeApiUrl('post')
		]); 
		return $this->success($form->getFormStructure());
	} 

	public function getRouteMap()
	{
		/* ... */
	} 
	
    /**
	 * @param $param
	 * @return MobileApp
	 */
	public function getAppSetting($param)
	{
		/* ... */
	}
}

<?php

/* ... */
Phpfox::getLib('module')
	->addAliasNames('post', 'Posts')
	->addServiceNames([
    
    // New API service register here
	'mobile.post_api' => Service\PostApi::class,
	'mobile.post_category_api' => Service\PostCategoryApi::class, 
	
    // Other Services of the app
	'post.category' => Service\Category\Category::class,
	'post.category.process' => Service\Category\Process::class,
	'post.api' => Service\Api::class,
	'post' => Service\Posts::class,
	'post.browse' => Service\Browse::class,
	'post.cache.remove' => Service\Cache\Remove::class,
	'post.callback' => Service\Callback::class,
	'post.process' => Service\Process::class,
	'post.permission' => Service\Permission::class,
	]);
/* ... */

<?php 
/**
Define RestAPI services. Note the name must be same as definition in start.php file
*/
$this->apiNames['mobile.post_api'] = \Apps\Posts\Service\PostApi::class;
$this->apiNames['mobile.post_category_api'] = \Apps\Posts\Service\PostCategoryApi::class; 
/**
Register Resource Name, This help auto generate routing for the resource
Note: resource name must be mapped correctly to resource api
*/
$this->resourceNames[\Apps\Posts\Api\Resource\PostResource::RESOURCE_NAME] = 'mobile.post_api';
$this->resourceNames[\Apps\Posts\Api\Resource\PostCategoryResource::RESOURCE_NAME] = 'mobile.post_category_api';

<?php

class PostApi extends AbstractResourceApi implements ActivityFeedInterface, MobileAppSettingInterface
{
    /**
    This method allow you add custom route for APIs
    Return an array with key is routing rule and mapping condition
    In this case, 'mobile/post/search-form' map to `searchForm` method
    */
    public function __naming()
    {
	    return [
		    'post/search-form'=> [
		    'get'=>'searchForm'
		    ]
	    ];
    }

    /**
    @param array $params
    @return mixed
    */
    function searchForm($params = [])
    {
	    $this->denyAccessUnlessGranted(PostAccessControl::VIEW);
	    /** @var PostSearchForm $form */
	    $form = $this->createForm(PostSearchForm::class, [
		    'title' =>'search',
		    'method' => 'GET',
		    'action' => UrlUtility::makeApiUrl('post')
		    ]); 
	    return $this->success($form->getFormStructure());
    }
}