Code in Chaos Inc.

RTFM! (or: Why every web developer should read RFC 2616)

ahmadnassri — Thu, 06 Oct 2011 00:48:56 -0400

As a software developer you always have to deal with users who find it difficult to use your software, or may -in one way or another- find it challenging to understand the interface or the functionality you’ve designed.
But that’s okay, because we are geeks who spends most of your adult lives behind a computer screen, building software and applications that -to us- are interesting and make perfect sense.
The reality is, without Graphic Designers to make our ugly interfaces sexy, and without Marketers to put together a clear message that explains what our thousand lines of code does, and without Sales Gurus to make these lines of text sell for $$$ we’d all be the laughing stock of the rest of the world, with our crazy, ugly looking products that do what any capable human being can do.

Try telling Don Draper back in the 50s that we could one day replace his secretary with a voice enabled application on a portable device that you can put in your pocket and operate it simply by touch it’s glass surface. oh and it will be called Siri.

He’d probably punch you square in the face.

So I’m never upset, offended or at the least, bothered, by any feedback or criticism from people using software that I’ve build, I’ve always found it to be an enlightening and humbling experience to see into the way other people think and react to technology that I’ve build.

But! those are people who are not developers, software engineers or in any way shape or form, familiar with the inner workings of the technology they use day to day.

I’ve always written software for people like that, and I always will. recently however, I created REST Console an HTTP Client for Google Chrome. this is an application directly targeted towards software developers, not your average consumer.

Software developers (in my mind) are people who can create code in the form of software and applications, much like the way artists create art.
Most of us don’t understand how the artist creates his art, we don’t really know what the tools they use are beyond our basic knowledge or a paint brush. But we all appreciate their work, some of us love, some don’t.
Software is the same as Art, many people don’t have the skill for it or the understanding of how it works, but they use it every day.

Ever since REST Console v.4.0.0 came out, I’ve been getting emails, comments, and github issues telling me its broken.

well, Its not. you are using it wrong!

Too aggressive? how about this: You don’t know how the internet works!

I find it utterly frustrating and completely shocking that the target audience for this particular software don’t know how to use it!

I figured Software Developers of all people need the least explanation, hand holding, or even guidance in using a software application that is SO specific in nature to what they do every day as part of their daily jobs (or hobbies, whatever) that I didn’t need to include a manual, or even do much explaining how the app works, they can figure it out themselves, they have the skills, they build apps like this every day!. Or at the very least, Google for some background information on the solution the application provides.

v4.0.0 of REST Console was a major re-write, but other than the interface and the code, little has changed or was added, except for one little tiny thing:
Header fields are no longer pre-populated with a default value.

This has apparently caused HAVOC.

It seems a significant number of Software Developers out there don’t really understand how the internet works, well, allow me to shine your way to a better understanding…

See, there is something interesting out there called RFC 2616 that, in simple terms: defines how HTTP requests are made over the internet.
and HTTP Requests are exactly what REST Console is built to do.

People were complaining that v4.0.0 is broken, why? because their POST payload is not being received on their servers.
It seems the mistake these developers have done (beyond not reading RFC 2616) is forgetting to set their Content-Type header before they send their POST requests.

This alone is not a big deal, I started telling people they may have forgotten to set their Content-Type header, and they proceeded to check the box to enable it and come back and complain that it still didn’t work.

Turns out none of these guys realized that they need to set their Content-Type to “application/x-www-form-urlencoded” which is the Internet media type for sending HTML Form Data, something they would have known have they read RFC 2616

RFC 2616 actually has no mention of “application/x-www-form-urlencoded”, it only references RFC 1867 regarding Form-based File Upload in HTML, which mentions “application/x-www-form-urlencoded” which is actually defined in HTML 4.01 Specification, Section 17.13.4.1 only to discuss its limitation and being: “inefficient for sending large quantities of binary data or text containing non-ASCII characters.” and suggests using “multipart/form-data” as it accommodates a wider spectrum of data to be transferred over HTTP.

I find it actually scary that some developers don’t know that.

REST Console is a tool to build HTTP requests, not emulate an HTML form. it’s that simple.

PHP (and other languages) expects the Content-Type header to be set to “application/x-www-form-urlencoded” so it would parse the POST url-encoded string into a $_POST variable … but that’s not how all HTTP requests are made.

While this is a “typical” behavior for sending data through HTML forms, you can in fact, send a payload of a url-encoded “key/value” string and tell the server its “application/xml”!

Its up to the HTTP client library to determine what to set the Content-Type header to, and to the server to determine how interpret the request body, based on the Content-Type header it receives …

I feel really frustrated writing this post, I shouldn’t have to, this should be common knowledge for people in our field, but there it is. and it scares me.

Based on how many people have complained about POST data not being sent, maybe I’ll make the Content-Type header pre-populated again, This post will not stop the questions, the bad reviews in the Chrome Web Store or the github issues. There are already a significant number of them, and people didn’t bother reading the replies I made. so why should this post help?

The one thing I’m now almost certain people will never do, is read RFC 2616

Please prove me wrong.

Programming a Twilio phone menu with TwiML & some PHP

ahmadnassri — Sun, 04 Sep 2011 10:43:00 -0400

Twilio allows your web application to easily make and receive phone calls and SMS text messages using a simple web service API and basic web programming skills like HTTP, XML, and REST. You can build hosted IVR, PBX and SMS applications with no up front costs and a very competitive pricing

With so many possibilities and mash-ups ideas, the sky is the limit to the things you can do with Twilio … however, in its most basic forms (and most popular usage I believe) Twilio lets you build a simple phone menu in no time at all.

I’m sure we will be utilizing Twilio in the future for some cool & rad Code in Chaos projects, but for now, we made a simple phone menu with a company directory that forwards the caller to the person’s personal phone number and a message recording option that will let the caller record a two minute message, then emails that message along with the caller ID information to a specified email address.

its a very simple implementation, we though we’d share it, since we found the Twilio samples a bit too complicated than what they should be, they rely on too many files for something that can be achieved with just one.

index.php

<? header('Content-Type: text/xml') ?>
<? include 'email.php' ?>
<?= '<?xml version="1.0" encoding="utf-8"?>' ?>
<Response>
    <? if (!array_key_exists('Digits', $_REQUEST)): ?>
        <Say voice="woman">You have reached Code in Chaos.</Say>
        <Redirect method="GET">index.php?Digits=0</Redirect>
    <? else: ?>
        <? if (array_key_exists('RecordingUrl', $_REQUEST)): ?>
            <? email($_REQUEST['RecordingUrl']) ?>
            <Say voice="woman">Thank you, we will contact you as soon as possible. Goodbye.</Say>
            <Hangup/>
        <? elseif (array_key_exists('Dial', $_REQUEST)): ?>
            <? switch (@$_REQUEST['Digits']):
                case '0': ?>
                    <Redirect method="GET">index.php?Digits=1</Redirect>
                    <? break ?>

                <? case '1': ?>
                    <Dial timeout="15" hangupOnStar="true">+16477007703</Dial>
                    <Say voice="woman">Failed to connect your call, please try again later. Goodbye.</Say>
                    <Hangup/>
                    <? break ?>

                <? case '*': ?>
                    <Redirect method="GET">index.php?Digits=0</Redirect>
                    <? break ?>

                <? default: ?>
                    <Say voice="woman">Invalid Entry.</Say>
                    <Redirect method="GET">index.php?Digits=1</Redirect>
            <? endswitch ?>
        <? else: ?>
            <? switch ($_REQUEST['Digits']):
                case '0': ?>
                    <Gather numDigits="1" timeout="10" action="index.php" method="POST">                        
                        <Say voice="woman">Main menu.</Say>
                        <Pause length="1"/>
                        <Say voice="woman">Press 1 for the company's directory.</Say>
                        <Say voice="woman">Press 2 to leave a message.</Say>
                        <Say voice="woman">Press 0 to repeat this menu.</Say>
                        
                    </Gather>

                    <? if (array_key_exists('Repeated', $_REQUEST)): ?>
                        <Say voice="woman">Goodbye.</Say>
                        <Hangup/>
                    <? else: ?>
                        <Redirect method="GET">index.php?Digits=0&Repeated=true</Redirect>
                    <? endif ?>
                    <? break ?>

                <? case '1': ?>
                    <Gather numDigits="1" timeout="10" action="index.php?Dial=true" method="POST">
                        <Say voice="woman">Company Directory.</Say>
                        <Pause length="1"/>                        
                        <Say voice="woman">For Ahmad Nassri, press 1.</Say>
                        <Pause length="2"/>
                        <Say voice="woman">Press 0 to repeat this menu.</Say>
                        <Say voice="woman">Press star to return to the main menu.</Say>
                    </Gather>

                    <? if (array_key_exists('Repeated', $_REQUEST)): ?>
                        <Say voice="woman">Goodbye.</Say>
                        <Hangup/>
                    <? else: ?>
                        <Redirect method="GET">index.php?Digits=1&Repeated=true</Redirect>
                    <? endif ?>
                    <? break ?>

                <? case '2': ?>
                    <Say voice="woman">Record your message after the tone, when finished, press the star key.</Say>
                    <Pause length="1"/>
                    <Say voice="woman">Please leave your name, number and email address and the reason for your call.</Say>
                    
                    <Record timeout="10" maxLength="120" action="index.php" method="POST" finishOnKey="*"/>
                    <? break ?>

                <? default: ?>
                    <Say voice="woman">Invalid Entry</Say>
                    <Redirect method="GET">index.php?Digits=0</Redirect>
            <? endswitch ?>
        <? endif ?>
    <? endif ?>
</Response>

email.php

<?php
function email($url) {
    $message = sprintf('<b>Caller:</b> %s<br/> <b>City:</b> %s<br/> <b>State:</b> %s<br/> <b>Country:</b> %s<br/>', $_REQUEST['From'], $_REQUEST['FromCity'], $_REQUEST['FromState'], $_REQUEST['FromCountry']);

    $boundary = uniqid();

    $headers = array(
        'From: Twilio <twilio@codeinchaos.com>',
        'Reply-To: No Reply <noreply@codeinchaos.com>',
        'MIME-Version: 1.0',
        'Content-Type: multipart/mixed; boundary = ' . $boundary,
        ''
    );

    $headers = join("\r\n", $headers);

    //plain text version of message
    $body = array(
        // plain text
        '--' . $boundary,
        'Content-Type: text/plain; charset=ISO-8859-1',
        'Content-Transfer-Encoding: base64',
        '',
        chunk_split(base64_encode(strip_tags($message))),
        // html
        '--' . $boundary,
        'Content-Type: text/html; charset=ISO-8859-1',
        'Content-Transfer-Encoding: base64',
        '',
        chunk_split(base64_encode($message)),
        // attachement
        '--' . $boundary,
        'Content-Type: audio/wav; name=message.wav',
        'Content-Transfer-Encoding: base64',
        'Content-Disposition: attachment',
        '',
        chunk_split(base64_encode(file_get_contents($url)))
    );

    $body = join("\r\n", $body);

    //send the email
    return @mail('contact@codeinchaos.com', 'New Voice Mail (' . $_REQUEST['CallSid'] . ')', $body, $headers);
}

Hi, I was about to install your REST Console from the Chrome web store. But why on earth do you need access to data on all websites I visit?

ahmadnassri — Tue, 09 Aug 2011 11:45:00 -0400

actually, REST Console doesn’t need access to all your “data” on all website, I think that’s mis-wording on Google’swebsite behalf.

the application asks for the following permissions:

“permissions”: [
“http://*/*”,
“https://*/*”
]

this basically allows the app to make HTTP calls to any URL, which is obviously the intent of the app, however it does not access any other information.

the application is open-source so you are free to checkout the inner workings of it at the github project page: http://github.com/codeinchaos/restconsole

REST Console - a Google Chrome REST/HTTP Client

ahmadnassri — Tue, 17 May 2011 22:00:00 -0400

“REST Console” is a REST/HTTP Client for Google Chrome to visualise and construct custom HTTP requests to test with any RESTful web service.

Features:

Syntax highlighting (multiple themes)
Custom headers
Construct POST or PUT body via raw input
Auto Complete
File upload
Easy query parameters creation
Add custom headers through intuitive ui
Authentication support: Plain, Basic, OAuth + Custom
Keyboard navigation and shortcuts
Customizable Interface

Resources

Follow us on Twitter: http://twitter.com/restconsole
Get the source code: https://github.com/codeinchaos/restconsole
Report issues: https://github.com/codeinchaos/restconsole/issues
Donate: https://flattr.com/thing/156628/REST-Console

Changelog

v3.0.6 UI enhancements + File uploads + “Save Default” Option
v3.0.5 More keyboard shortcuts
v3.0.4 Bugfixes
v3.0.3 Keyboard navigation + Bugfixes
v3.0.2 Syntax Highlighting themes + Collapsible sections + Options
v3.0.1 RAW request body + Bugfixes
v3.0.0 Brand New UI
v2.1.1 Bugfixes
v2.1 Added OAuth1.0a support + bug fixes.
v2.0 Revamped Design.
v1.0 Released!

Coming Soon:

Request history manager
URL auto complete

RESTful services with Zend Framework (Part 2)

ahmadnassri — Fri, 04 Mar 2011 18:19:00 -0500

Previously, I covered the basic steps to create a RESTful Application with Zend Framework.

Today, we’re going to look into context switching, which will allow us to server different response formats based on the “Accept” HTTP header

I’ve seen many wasy of doing this, like using view scripts to generate JSON or XML, or creating the response DOM document manually, etc … but I found the simplest way is to stick to what we know, and what we know best in ZF is the setting the result variables through the view object, which we can easily serialize into any format we want using Zend’s own Zend_Serializer.

Zend Framework comes with a ContextSwitch action helper, but its only good to do JSON, so lets extend it and add more formats, I’m going to add AMF3, XML, PHP serialization, but you can add your own using either standard Zend_Serializer Adapters or building your own like we will for XML serialization

class REST_Controller_Action_Helper_ContextSwitch extends Zend_Controller_Action_Helper_ContextSwitch
{
    protected $_autoSerialization = true;

    protected $_availableAdapters = array(
        'amf'   => 'Zend_Serializer_Adapter_Amf3',
        'json'  => 'Zend_Serializer_Adapter_Json',
        'xml'   => 'REST_Serializer_Adapter_Xml',
        'php'   => 'Zend_Serializer_Adapter_PhpSerialize'
    );

    public function __construct($options = null)
    {
        if ($options instanceof Zend_Config)
        {
            $this->setConfig($options);
        }
        elseif (is_array($options))
        {
            $this->setOptions($options);
        }

        if (empty($this->_contexts))
        {
            $this->addContexts(
                array(
                    'amf' => array(
                        'suffix'    => 'json',
                        'headers'   => array(
                            'Content-Type' => 'application/octet-stream'
                        ),
                        'callbacks' => array(
                            'init' => 'initAbstractContext',
                            'post' => 'restContext'
                        ),
                    ),

                    'json' => array(
                        'suffix'    => 'json',
                        'headers'   => array(
                            'Content-Type' => 'application/json'
                        ),
                        'callbacks' => array(
                            'init' => 'initAbstractContext',
                            'post' => 'restContext'
                        ),
                    ),

                    'xml' => array(
                        'suffix'    => 'xml',
                        'headers'   => array(
                            'Content-Type' => 'application/xml'
                        ),
                        'callbacks' => array(
                            'init' => 'initAbstractContext',
                            'post' => 'restContext'
                        ),
                    ),

                    'php' => array(
                        'suffix'    => 'php',
                        'headers'   => array(
                            'Content-Type' => 'text/php'
                        ),
                        'callbacks' => array(
                            'init' => 'initAbstractContext',
                            'post' => 'restContext'
                        )
                    )
                )
            );
        }

        $this->init();
    }

    public function initAbstractContext()
    {
        if (!$this->getAutoSerialization())
        {
            return;
        }

        $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
        $view = $viewRenderer->view;

        if ($view instanceof Zend_View_Interface)
        {
            $viewRenderer->setNoRender(true);
        }
    }

    public function restContext()
    {
        if (!$this->getAutoSerialization())
        {
            return;
        }

        $view = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer')->view;

        if ($view instanceof Zend_View_Interface)
        {
            if (method_exists($view, 'getVars'))
            {
                $data = $view->getVars();

                if (count($data) !== 0)
                {
                    $serializer = new $this->_availableAdapters[$this->_currentContext];
                    $body = $serializer->serialize($view->getVars());

                    if ($this->_currentContext == 'xml')
                    {
                        $stylesheet = $this->getRequest()->getHeader('X-XSL-Stylesheet');

                        if ($stylesheet !== false and !empty($stylesheet))
                        {
                            $body = str_replace('', sprintf('', $stylesheet), $body);
                        }
                    }

                    if ($this->_currentContext == 'json')
                    {
                        $callback = $this->getRequest()->getParam('jsonp-callback', false);

                        if ($callback !== false and !empty($callback))
                        {
                            $body = sprintf('%s(%s)', $callback, $body);
                        }
                    }

                    $this->getResponse()->setBody($body);
                }
            }
        }

    }

    public function setAutoSerialization($flag)
    {
        $this->_autoSerialization = (bool) $flag;
        return $this;
    }

    public function getAutoSerialization()
    {
        return $this->_autoSerialization;
    }

}

for the most part, there is nothing special about this Class, it relies mostly on Zend_Controller_Action_Helper_ContextSwitch and mimics its logic:
The constructor adds the new contexts and defines the Content-Type header to send with the response.
initAbstractContext disables the view renderer completely (this replaces the method we used in Part 1)
restContext is where the magic happens!

The Magic!

first we grab the viewRenderer object through Zend_Controller_Action_HelperBroker and grab all the variables set from the Controller logic.
Next we run those variables through our serializer and set the serialized value as the response body!

You’ll notice there is some extra magic happening in there around XML and XSL Stylesheets. this is something I added to facilitate the usage of XSL Stylesheets in an XML Response, all it does is expect an optional X-XSL-Stylesheet header from the client request and inserts the xml-stylesheet declaration to the XML response.
That way if you are viewing this XML in a modern browser, the browser will automatically render the page into a more readable format using the specified XSL stylesheet.

We also look in the request for a jsonp-callback parameter to wrap around the body JSON response, this is most helpful when building web clients.

Note: I’m using a custom Zend_Serializer_Adapter: REST_Serializer_Adapter_Xml, which is a custom XML serialization class I’ve created, there is no point in describing it in this article since its irrelevant to the main topic, you can find the source in the repository.

Now we need to apply the ContextSwitch to each of our controllers actions, the easiest way to do so is with an Action Helper:

class REST_Controller_Action_Helper_RestContexts extends Zend_Controller_Action_Helper_Abstract
{
    protected $_contexts = array(
        'php',
        'xml',
        'json',
        'amf'
    );

    protected $_actions = array(
        'options',
        'head',
        'index',
        'get',
        'post',
        'put',
        'delete',
        'error'
    );

    public function preDispatch()
    {
        $controller = $this->getActionController();

        if (!$controller instanceof Zend_Rest_Controller)
        {
            return;
        }

        $this->_initContexts();
    }

    protected function _initContexts()
    {
        $contextSwitch = $this->getActionController()->getHelper('contextSwitch');

        $contextSwitch->setAutoSerialization(true);

        foreach ($this->_contexts as $context)
        {
            foreach ($this->_actions as $action)
            {
                $contextSwitch->addActionContext($action, $context);
            }
        }

        $contextSwitch->initContext();
    }
}

What this helper does is execute on preDispatch and set the all contexts on all actions of the current controller.

Now we need to initialize those two helpers, that can be done in Bootstrap.php:

    protected function _initActionHelpers()
    {
        $contextSwitch = new REST_Controller_Action_Helper_ContextSwitch();
        Zend_Controller_Action_HelperBroker::addHelper($contextSwitch);

        $restContexts = new REST_Controller_Action_Helper_RestContexts();
        Zend_Controller_Action_HelperBroker::addHelper($restContexts);
    }

But how is the context set for each request? by default, ZF uses the ?format= query parameter to define the context, but that is not very RESTful! the most elegant way is to rely on HTTP Accept headers to tell us what kind of response the client expects, to accomplish this, we need a plugin:

class REST_Controller_Plugin_RestHandler extends Zend_Controller_Plugin_Abstract
{
    public function dispatchLoopStartup(Zend_Controller_Request_Abstract $request)
    {
        $this->getResponse()->setHeader('Vary', 'Accept');

        $mimeType = $this->getMimeType($request->getHeader('Accept'));

        switch ($mimeType) {
            case 'text/xml':
            case 'application/xml':
                $request->setParam('format', 'xml');
                break;

            case 'application/octet-stream':
                $request->setParam('format', 'amf');
                break;

            case 'text/php':
                $request->setParam('format', 'php');
                break;

            case 'application/json':
            default:
                $request->setParam('format', 'json');
                break;
        }
    }

    private function getMimeType($mimeTypes = null)
    {
        // Values will be stored in this array
        $AcceptTypes = Array ();

        // Accept header is case insensitive, and whitespace isn't important
        $accept = strtolower(str_replace(' ', '', $mimeTypes));

        // divide it into parts in the place of a ","
        $accept = explode(',', $accept);

        foreach ($accept as $a)
        {
            // the default quality is 1.
            $q = 1;

            // check if there is a different quality
            if (strpos($a, ';q='))
            {
                // divide "mime/type;q=X" into two parts: "mime/type" i "X"
                list($a, $q) = explode(';q=', $a);
            }

            // mime-type $a is accepted with the quality $q
            // WARNING: $q == 0 means, that mime-type isn't supported!
            $AcceptTypes[$a] = $q;
        }

        arsort($AcceptTypes);

        // let's check our supported types:
        foreach ($AcceptTypes as $mime => $q)
        {
            if ($q && in_array($mime, $this->availableMimeTypes))
            {
                return $mime;
            }
        }
        // no mime-type found
        return null;
    }

The plugin does two things: first it sets the response “Accept” header to “Vary” (this tells HTTP clients that we are able to serve multiple formats) then it sets the “format” parameter based on the best mime-type described in the request’s Accept header (the utility method “getMimeType” extracts and sorts the differnt values)

Here you can set any number of mime-types you want to support and match them with Serializers we’ve created previously.

Next, enabled this plugin in your application.ini

resources.frontController.plugins[] = "REST_Controller_Plugin_RestParams"

Going back to the FooController we created in Part 1, lets first get rid of the init method we created and modify the action methods to something like this:

    public function optionsAction()
    {
        $this->view->message = 'Resource Options';
        $this->getResponse()->setHttpResponseCode(200);
    }

    public function indexAction()
    {
        $this->view->resources = array();
        $this->getResponse()->setHttpResponseCode(200);
    }

    public function headAction()
    {
        $this->getResponse()->setHttpResponseCode(200);
    }

    public function getAction()
    {
        $this->view->id = $this->_getParam('id');
        $this->view->resource = new stdClass;
        $this->getResponse()->setHttpResponseCode(200);
    }

    public function postAction()
    {
        $this->view->message = 'Resource Created';
        $this->getResponse()->setHttpResponseCode(201);
    }

    public function putAction()
    {
        $this->view->message = sprintf('Resource #%s Updated', $this->_getParam('id'));
        $this->getResponse()->setHttpResponseCode(201);
    }

    public function deleteAction()
    {
        $this->view->message = sprintf('Resource #%s Deleted', $this->_getParam('id'));
        $this->getResponse()->setHttpResponseCode(200);
    }

Test it in the command line:

curl -v -H "Accept: application/json" http://localhost/v1/foo
curl -v -H "Accept: application/json" -X HEAD http://localhost/v1/foo
curl -v -H "Accept: application/json" -X OPTIONS http://localhost/v1/foo/1
curl -v -H "Accept: application/json" -X GET http://localhost/v1/foo/1
curl -v -H "Accept: application/json" -X POST http://localhost/v1/foo
curl -v -H "Accept: application/json" -X PUT -d '' http://localhost/v1/foo/1
curl -v -H "Accept: application/json" -X DELETE http://localhost/v1/foo/1

curl -v -H "Accept: application/xml" http://localhost/v1/foo
curl -v -H "Accept: application/xml" -X HEAD http://localhost/v1/foo
curl -v -H "Accept: application/xml" -X OPTIONS http://localhost/v1/foo/1
curl -v -H "Accept: application/xml" -X GET http://localhost/v1/foo/1
curl -v -H "Accept: application/xml" -X POST http://localhost/v1/foo
curl -v -H "Accept: application/xml" -X PUT -d '' http://localhost/v1/foo/1
curl -v -H "Accept: application/xml" -X DELETE http://localhost/v1/foo/1

You’ll notice that we are no longer setting the response body text directly, but rather setting the view object variables which will be serialized according to the Accept header we are sending in the request!
like I said, MAGIC!

All this is great, we got all sorts of magic happening in the output, but what about the input? shouldn’t we accept multiple formats as well?…
hellz yeah! lets do it!

Lets go back and edit REST_Controller_Plugin_RestHandler and add the following:

    private $availableMimeTypes = array(
        'php'           => 'text/php',
        'xml'           => 'application/xml',
        'json'          => 'application/json',
        'amf'           => 'application/octet-stream',
        'urlencoded'    => 'application/x-www-form-urlencoded'
    );

    private $methods = array('OPTIONS', 'HEAD', 'INDEX', 'GET', 'POST', 'PUT', 'DELETE');

    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        if (!in_array(strtoupper($request->getMethod()), $this->methods))
        {
            $request->setActionName('options');
            $request->setDispatched(true);

            $this->getResponse()->setHttpResponseCode(405);

            return;
        }
        else
        {
            $contentType = $this->getMimeType($request->getHeader('Content-Type'));
            $rawBody = $request->getRawBody();

            if (!empty($rawBody))
            {
                try
                {
                    switch ($contentType)
                    {
                        case 'application/json':
                            $params = Zend_Json::decode($rawBody);
                            break;

                        case 'text/xml':
                        case 'application/xml':
                            $json = Zend_Json::fromXml($rawBody);
                            $params = Zend_Json::decode($json, Zend_Json::TYPE_OBJECT)->request;
                            break;

                        case 'application/octet-stream':
                            $serializer = new Zend_Serializer_Adapter_Amf3();
                            $params = $serializer->unserialize($rawBody);
                            break;

                        case 'text/php':
                            $params = unserialize($rawBody);
                            break;

                        case 'application/x-www-form-urlencoded':
                            $params = array();
                            parse_str($rawBody, $params);
                            break;

                        default:
                            $params = $rawBody;
                            break;
                    }

                    $request->setParams((array) $params);
                }
                catch (Exception $e)
                {
                    this->view->message = $e->getMessage();;
                    $this->getResponse()->setHttpResponseCode(400);
        
                    $request->setControllerName('error');
                    $request->setActionName('error');
                    $request->setParam('error', $error);

                    $request->setDispatched(true);

                    return;
                }
            }
        }
    }

The preDispatch runs just before any Controller method is initiated and does two things:
first, it checks if the requested HTTP Method is acceptable, and sends an OPTIONS response if its not (in accordance with the HTTP spec)
Then it looks for the request’s “Content-Type” header and un-serialze the raw body with a matching Zend_Serializer

and just like MAGIC our application can now parse different request formats!

Update [Monday, 07 March 2011]: added JSONP support.

Update [Sunday, 01 January 2012]: This article is out of date, please refer to the GitHub repo for updated instructions, the same principles still apply, but with some changes and slight modifications.

Note: all examples used are part of RESTful Zend Framework on GitHub

RESTful services with Zend Framework (Part 1)

ahmadnassri — Fri, 04 Feb 2011 13:34:00 -0500

I previously wrote about the opensource project I’ve created: RESTful Zend Framework which is a custom Zend Framework Application built to act as a REST API.

This is the first of couple of follow up articles describing how I built the REST implementation from scratch.

Some Assumptions:

I’m going to skip the initial project creation and assume you already know the basics, if not, spend some time on Google figuring it out first (I don’t recommend the ZF documentation since it’s more confusing than helpful!)

My entire application is meant to be a REST API, I don’t have a mixed mode of web controllers and REST controllers, though it is easily possible to have both, with very little modifications to fit your needs once you read through the steps.

I believe APIs should have maintainable revisions and as such I’ve used Zend Framework Modules to separate my API revisions, again, its easy enough to skip that and suit your own needs.

Configuration:

As always, the first thing you’d wanna do is customize your application.ini file, here are the lines I’ve added:

resources.frontController.defaultModule = "v1"
resources.frontController.moduleDirectory = APPLICATION_PATH "/modules"
resources.frontController.moduleControllerDirectoryName = "controllers"

resources.modules = ""

You should also remove the following line from your application.ini file, otherwise ZF will complain about missing Module Bootstrap calsses.

resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"

This will enable Modules in your Application and setup the default module name as “v1”. (At this point you would want to re-organize your directory structure to accommodate modules.)

You can skip this step if you don’t want Modules as part of your Application.

Setting up the REST Route:

Now we need to setup routing, ZF comes with its own REST route, so lets make sure all our controllers are setup to go through it by adding the following to our application.ini

resources.router.routes.rest.type = Zend_Rest_Route

The REST route controls the URL scheme for our application, more on that later.

Note: this method will apply the REST route to ALL controllers If you are thinking of having a mix of REST controllers and regular Zend_Action_Controller you need to customize the route rules by initiating it in your Bootstrap.php instead.

At this point, some clean-up of your application directory is probably a good idea …
depending on your set-up of the REST route, you might want to delete the views folder if you apply REST to all your controllers.
I created a new folder named “v1” under application/modulesto match my module setup, and moved the controllers & models folders into it.

Controllers vs. Resources

In a typical ZF Application you would want to have your controllers extend Zend_Controller_Action, but in this case, we want them to extend Zend_Rest_Controller.

class FooController extends Zend_Rest_Controller

Zend_Rest_Controller is just an abstract controller with a list of predefined Actions that we should implement in each of our Controllers:

class FooController extends Zend_Rest_Controller
{
    public function indexAction()
    {}

    public function getAction()
    {}

    public function postAction()
    {}

    public function putAction()
    {}

    public function deleteAction()
    {}
}

The first thing you’ll notice is that the Actions represent the most basic HTTP Methods: GET, POST, PUT and DELETE which are the core of our RESTful implementation. at this point you should start thinking of your Controllers as Resources (you might wanna read up on REST to clearify this bit)
Also, we didn’t create any view scripts for this Controller, and as we are not going to need the view renderer anymore, lets disable it:

public function init()
{
    $this->_helper->viewRenderer->setNoRender(true);
}

this is a temporary solution and will only disable the view rendered for this controller, we eventually want to disable it for all our REST controllers (covered in later steps).

Now lets add some response output and give it a go!

public function indexAction()
{
    $this->getResponse()->setBody('Hello World');
    $this->getResponse()->setHttpResponseCode(200);
}

public function getAction()
{
    $this->getResponse()->setBody('Foo!');
    $this->getResponse()->setHttpResponseCode(200);
}

public function postAction()
{
    $this->getResponse()->setBody('resource created');
    $this->getResponse()->setHttpResponseCode(200);
}

public function putAction()
{
    $this->getResponse()->setBody('resource updated');
    $this->getResponse()->setHttpResponseCode(200);
}

public function deleteAction()
{
    $this->getResponse()->setBody('resource deleted');
    $this->getResponse()->setHttpResponseCode(200);
}

We test this by using CURL in the command line:

curl -v http://localhost/v1/foo
curl -v -X GET http://localhost/v1/foo/id
curl -v -X POST http://localhost/v1/foo
curl -v -X PUT -d '' http://localhost/v1/foo/id
curl -v -X DELETE http://localhost/v1/foo/id

you’ll notice that I’ve added /id to GET, PUT, DELETE. This is by design of course, remember the REST route you setup earlier? well this is where it comes to play! now that you are creating Resources not controllers, there are no need for any other actions other than to CREATE, READ, UPDATE & DELETE individual resources, otherwise known as CRUD and naturally: READ, UPDATE & DELETE require a resource identifier so Zend_Rest_Route takes care of mapping the URLs to match. here’s the breakdown of how the HTTP methods map to CRUD functions:

POST = CREATE
GET = READ
PUT = UPDATE
DELETE = that’s right, you guessed it! DELETE!

That leaves one: The index action handles index/list requests; it should respond with a list of the requested resources.

Now lets modify our logic to give a proper REST response:

public function indexAction()
{
    $this->getResponse()->setBody('List of Resources');
    $this->getResponse()->setHttpResponseCode(200);
}

public function getAction()
{
    $this->getResponse()->setBody(sprintf('Resource #%s', $this->_getParam('id')));
    $this->getResponse()->setHttpResponseCode(200);
}

public function postAction()
{
    $this->getResponse()->setBody('Resource Created');
    $this->getResponse()->setHttpResponseCode(201);
}

public function putAction()
{
    $this->getResponse()->setBody(sprintf('Resource #%s Updated', $this->_getParam('id')));
    $this->getResponse()->setHttpResponseCode(201);
}

public function deleteAction()
{
    $this->getResponse()->setBody(sprintf('Resource #%s Deleted', $this->_getParam('id')));
    $this->getResponse()->setHttpResponseCode(200);
}

Now lets test again:

curl -v http://localhost/v1/foo
curl -v -X GET http://localhost/v1/foo/1
curl -v -X POST http://localhost/v1/foo
curl -v -X PUT -d '' http://localhost/v1/foo/1
curl -v -X DELETE http://localhost/v1/foo/1

There, nice and clean RESTful response!

Now lets add some more HTTP Mehods beyond the basic GET, POST, PUT, DELETE.
Two very popular HTTP methods are: HEAD and OPTIONS.

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI.
This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification (cache).

Zend_Rest_Controller does not force any methods other than ones we’ve already used, and since HEAD and OPTIONS in my example behave the same across all controllers, lets create a new Class REST_Controller and implement the optionsAction and headAction there.

First step is to add the custom REST_ namespace to our application.ini:

autoloaderNamespaces.rest = "REST_"

the REST_Controller class should look something like this:

abstract class REST_Controller extends Zend_Rest_Controller
{
    public function headAction()
    {
        // you should add your own logic here to check for cache headers from the request
        $this->getResponse()->setBody(null);
    }

    public function optionsAction()
    {
        $this->getResponse()->setBody(null);
        $this->getResponse()->setHeader('Allow', 'OPTIONS, HEAD, INDEX, GET, POST, PUT, DELETE');
    }
}

now lets make sure our FooController extends the newly created class:

class FooController extends REST_Controller

Now lets test the new actions:

curl -v -X HEAD http://localhost/v1/foo
curl -v -X OPTIONS http://localhost/v1/foo/1

Update [Friday, 04 March 2011]: using application.ini to setup the REST route, added OPTIONS, HEAD actions

In the next part I’ll explain how to add context switching and add multi format input/output

Note: all examples used are part of RESTful Zend Framework on GitHub

RESTful Zend Framework

ahmadnassri — Wed, 02 Feb 2011 15:17:00 -0500

This seems to be one of the most obscure topics on the web, building a RESTful Application or Services with Zend Framework, I’ve spent a lot of time researching different solutions and eventually came up with the perfect one, but that was a long time ago and ever since, I’ve had to re-trace my steps every time I need to create RESTful services with ZF.

So to make my life easier and to contribute something back to the community, I’ve collected my RESTful implementation of Zend Framework and created a Google Code Project.

I will be posting a follow up article describing the steps in which you can re-create the same solution, which should serve a good documentation of the source code.

Hello World!

ahmadnassri — Fri, 21 Jan 2011 11:59:00 -0500

Being in the Tech industry, and since we’re all hardcore geeks, it’s obligatory to start our blog with the traditional “Hello World” which carries a sense of adventure for us! after all, every project starts with a few lines of code that print out “Hello World”.

World, say hello to <Code:in Chaos/>.

[queue awesomeness]