CakePHP RestKit Plugin - HAL responses when viewing entities

gistfile1.md

##CakePHP RestKit Plugin - HAL responses when viewing entities##

More information about the HAL convention can be found at http://stateless.co/hal_specification.html

Examples:

• Example 1: basic response
• Example 2: basic response with an _id field pointing to an internal resource (automatic)
• Example 3: basic response with an _id field pointing to an external resource (manual)

EXAMPLE 1

Basic response

public function view($id) {
	$result = $this->Country->find('first', array(
	    'fields' => array('id', 'name', 'iso_alpha3'),
	    'conditions' => array(
		'Country.id' => $id,
		'Country.enabled' => true)));

	if ($result) {
		$this->set(array(
		    'Country' => $result,
		    '_serialize' => array('Country')));
	}
}

URI: http://your.api.com/country/1.json

{
   "_links":
   {
       "self":
       {
           "href": "/countries/1"
       }
   },
   "name": "Netherlands",
   "iso_alpha3": "NLD"
}

URI: http://your.api.com/country/1.xml

<?xml version="1.0" encoding="UTF-8"?>
<resource rel="country" href="/countries/1">
	<name>Netherlands</name>
	<iso_alpha3>NLD</iso_alpha3>
</resource>

EXAMPLE 2

Basic response with automagic linking to internal resources based on detected _id field(s).

In this case the currency_id field triggers the internal link generator.

public function view($id) {
	$result = $this->Country->find('first', array(
	    'fields' => array('id', 'name', 'iso_alpha3', 'currency_id'),
	    'conditions' => array(
		'Country.id' => $id,
		'Country.enabled' => true)));

	if ($result) {
		$this->set(array(
		    'Country' => $result,
		    '_serialize' => array('Country')));
	}
}

URI: http://your.api.com/country/1.json

{
  "_links": {
	"self": {
	  "href": "/countries/1"
	},
	"currency": {
	  "href": "/currencies/1"
	}
  },
  "name": "Netherlands",
  "iso_alpha3": "NLD"
}

URI: http://your.api.com/country/1.xml

<?xml version="1.0" encoding="UTF-8"?>
<resource rel="country" href="/countries/1">
	<link rel="currency" href="/currencies/1"/>
	<name>Netherlands</name>
	<iso_alpha3>NLD</iso_alpha3>
</resource>

EXAMPLE 3

Basic view action where we flag an _id field as 'foreign' because it points to an external resource (not hosted by our CakePHP HalKit API).

In this real-life example the geoname_id can be used for various calls to the ws.geonames.org API so we choose to provide the id as a value (and not as a resource-link). This way the API-consumer can use it however he sees fit, e.g.

• http://ws.geonames.org/get?geonameId=2750405
• http://ws.geonames.org/get?geonameId=2750405&lang=nl
• http://ws.geonames.org/getJSON?geonameId=2750405

Controller function:

public function view($id) {
	$result = $this->Country->find('first', array(
	    'fields' => array('id', 'name', 'iso_alpha3', 'geoname_id'),
	    'conditions' => array(
			'Country.id' => $id,
			'Country.enabled' => true)));

	if ($result) {
		$this->set(array(
		    'Country' => $result,
		    '_serialize' => array('Country'),
		    'options' => array(
				'foreignFields' => array('geoname_id'))));
	}
}

URI: http://your.api.com/country/1.json

{
   "_links":
   {
       "self":
       {
           "href": "/countries/1"
       }
   },
   "name": "Netherlands",
   "iso_alpha3": "NLD",
   "geoname_id": "2750405"
}

URI: http://your.api.com/country/1.xml

<?xml version="1.0" encoding="UTF-8"?>
<resource rel="country" href="/countries/1">
	<name>Netherlands</name>
	<iso_alpha3>NLD</iso_alpha3>
	<geoname_id>2750405</geoname_id>
</resource>