Formatters interface changed but was not documented

As an example, in contrast to Peter Bliss' tutorial (which is what I worked out some months before that, the two parts of the now correct fix are:

1. Implement hook_rest_server_response_formatters_alter

/**
 * Implementation of hook_rest_server_response_formatters_alter
 * Note that we are now modifying 'formatter class', rather than 'view'
 */
function hook_rest_server_response_formatters_alter(&$formatters) {
  if (!empty($formatters['xml']['formatter class'])) {
    $formatters['xml']['formatter class'] = 'BetterRESTServerView';  
  }
}

2. Note now that the 'formatter class' no longer derives from RESTServerViewBuiltIn, but implements the ServicesFormatterInterface interface. I choose to derive from ServicesXMLFormatter, which implements this interface.

 class BetterRESTServerView extends ServicesXMLFormatter {

   /**
     * Note that the signature of render() has changed;  $data is new.  
     *  The previous signature was render(void).
     */
   public function render($data) {
    if (is_object($data) and $data instanceof SimpleXMLElement) {
      return $this->render_better_xml($data);
    }
    else {
      return parent::render($data);
    }
  }

  //my implementation omitted...

}

Yuriy looks to have made this mod on 15 April 2013 (commit 472fe93098c870109d4830742). I'm fine with the fix, but since the needed mod is not really "discoverable" -- I figured it out by following this stuff around in the debugger for a couple of hours, tough for most folks to do -- documentation of the formatting system is sorely needed.

Kyle -- to be clear, stability of APIs are an important part of reliability. If you change a low level API -- especially if you encourage other developers to use it, which was done in this case -- the dependent code will break, and in a very subtle way. So yeah, the change as made on 15 April 2013 did indeed break code. It made code using your module unreliable.

I don't really mean to YELL, but it was difficult to get needed action from you folks on this stuff. No, you don't use XML. But folks like Twilio do, and we can't control how they define their APIs. We only consume those APIs. I can offer patches, and try to work on them if there's a quick enough of a turn over from the module owners to make futzing with a patch practical.

You did get back to me, but some months after I'd solved the issue and moved on, as most developers need to do. Looking at the issues queue, it appears that at least 3 developers stumbled on related issues after that point. Yuriy made some changes rough a year thereafter that made the issue easier for developers to deal with, which, again, was a good thing. But it did break the fix I worked out from first principles, and that Paul Bliss independently worked out a few months later, and documented on his blog.

I know you're a volunteer on this, like most everybody else, and I thank you for your efforts. But it's worth thinking how to make the process on Services a bit more "user friendly" for developers who know your module well enough to patch, since if the process works a bit better, more of that work will get back to the community in a timely fashion.

"I am curious though what Twilio API consumption has to do with Drupal Services exposed APIS? Not to mention that they offer JSON, they are not forcing you use to use XML."

At least as I read the docs, the "reply" portion of the callback is XML. The API will accept JSON or POST style key value pairs going in, but at least in my experience, the only thing it will accept for the reply is TwilML. A valid reply using the currently preferred API is something like

<?xml version="1.0" encoding="UTF-8"?>
<Response><Message>YOU RANG??</Message></Response>

Since the default formatter wants to modify the reply to

<?xml version="1.0" encoding="UTF-8"?>
<reply><Message>YOU RANG??</Message></reply>

this is a problem, since Twilio will reject it, and send nothing. Which was the thing I was trying to debug earlier today. Overriding the formatter prevents this.

Just for completeness: a tutorial page from the Twilio web site: https://www.twilio.com/docs/quickstart/php/sms/replying-to-sms-messages