Zend_Service Contributor Guidelines?

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Zend_Service Contributor Guidelines?

Duo Zheng
I’ve been thinking that maybe a Zend_Service contributor guidelines wiki entry should be created. I think a contributors guide specific to this section would be beneficial. As the number of components grow in the Zend_Service_* section, it’d be nice if the components followed a ZF standard and had more consistency. While every web service implementation is indeed different, there are many aspects when building a ZF client that could become guidelines or “best practices”.  I think this may encourage future proposals and make it easier for others to write for Zend_Service_*. Please note that I don’t want to force a certain method, but merely promote a “good way” on doing things especially if it is backed by Zend and the community.

While I was working on the Zend_Service_Tumblr component, I’ve ran into some implementation specifics I wasn’t 100% sure of or if Zend had a suggested approach for. I’ve used what I believe would be best for ZF when planning, but maybe it could be documented to help others.

Some examples:

Validation
Should the ZF client validate or let the web service do the validation? Maybe a mix?

Validating everything locally could be very time consuming and sometimes not possible if the validation rules aren’t stated in the web service documentation. At the same time validating everything remotely may not be acceptable under certain circumstances. Validating a number, length of a string..etc is easy, but validating an file upload may not be or even possible. I wanted to be somewhat consistent so which way should I go?

Testability
While there are tests for every Zend_Service component, there isn’t a normal guideline to on what approach to use or how testable it is. For example, if the component required a Zend_Http_Client instance, should the component be injected (optionally usually) in the constructor or using setters? If the Zend_Http_Client is instantiated inside the component, where should it happen?

Constructor
(Zend_Service_Simpy)

public function __construct($username, $password)
{
        /**
         * @see Zend_Service_Rest
         */
        require_once 'Zend/Rest/Client.php';
        $this->http = new Zend_Http_Client;
        $this->http->setAuth($username, $password);
}

Lazy loading
(Zend_Service_Amazon)

public function getRestClient()
{
        if($this->_rest === null) {
            $this->_rest = new Zend_Rest_Client();
        }
        return $this->_rest;
}

In addition some of the ZF client’s don’t allow a setRestClient() or a setHttpClient method (this may be for good reason though) so you can’t override the normal instances without extending the class and having your own implementation. This is more nit picky, but it’d be nice if you were using many Zend_Service components to know offhand as it is consistent. This is also important when writing tests for your own application. You may want to inject a test Http adapter. Right now certain components require mock objects to do so while others have a simple injection method.

How much of the API should be implemented?
Should there be some guidelines on how “full” an API needs to be implemented? For example Zend_Service_Flickr only supports “fetching” methods and no creating or updating methods. I know this was created in the early days, but should partial implementations be accepted in cases like Flickr where it seems obvious to support more at the current day?

Thanks for reading.