Question

I want to implement a RESTful design in Zend Framework 1. I am not sure how to document the resources and which methods are allowed and which extra parameters can be supplied.

My current implementation uses a controller name as resource and the HTTP methods are the action names. I am already sending “Allow” in the header containing:

GET, PUT, PATCH, LINK, UNLINK, POST, DELETE, HEAD, OPTIONS

I am wondering how I can document the possible and required parameters for the client.

1. Is there a common DocBlock convention?
2. Is it feasible to “autodocument” the possible extra parameters with HTTP headers (like the “Allow” part)

Right now I am making up DocBlock attributes and sending them on an “OPTIONS” request.

/**
 * @route /data/results
 * @method GET
 * @requiredParams pid The project ID
 * @queryParams tid The team ID
 */
public function getAction()
{
    $pid = $this->_getParam('pid');
    $teamId = $this->_getParam('tid');

    if (null === $pid) {
        $this->getResponse()->setHttpResponseCode(400);
        $this->getResponse()
        ->setBody(Zend_Json::encode(array('required parameters missing')));
    } else {
        $this->getResponse()->setBody(Zend_Json::encode(array($pid, $teamId)));
        $this->getResponse()->setHeader('Content-Type', 'application/json');
        $this->getResponse()->setHttpResponseCode(200);
    }
}

public function optionsAction()
{
    $reflect = new Zend_Reflection_Class($this);
    foreach (explode(',',$this->getAllowedMethods()) as $method) {
        $action = strtolower(trim($method)) . 'Action';
        try {
            $docs[] = $method.' '.$reflect->getMethod($action)
                    ->getDocblock()->getContents();
        } catch(Zend_Reflection_Exception $e) {

        }
    }

    $this->getResponse()->setBody(implode("\n",$docs));
    $this->getResponse()->setHttpResponseCode(200);
}

Answer 1

There seem to be not accepted standards. A good resource is:

https://github.com/nelmio/NelmioApiDocBundle

for the Symfony2 framework.