documentation/manual/en/module_specs/Zend_Rest_Client.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.rest.client">
   4     <title>Zend_Rest_Client</title>
   5
   6     <sect2 id="zend.rest.client.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             Using the <classname>Zend_Rest_Client</classname> is very similar to using
  11             <code>SoapClient</code> objects (<ulink
  12             url="http://www.php.net/soap">SOAP web service extension</ulink>).
  13             You can simply call the REST service procedures as
  14             <classname>Zend_Rest_Client</classname> methods. Specify the service's full
  15             address in the <classname>Zend_Rest_Client</classname> constructor.
  16         </para>
  17
  18         <example id="zend.rest.client.introduction.example-1">
  19             <title>A basic REST request</title>
  20
  21             <programlisting language="php"><![CDATA[
  22 /**
  23  * Connect to framework.zend.com server and retrieve a greeting
  24  */
  25 $client = new Zend_Rest_Client('http://framework.zend.com/rest');
  26
  27 echo $client->sayHello('Davey', 'Day')->get(); // "Hello Davey, Good Day"
  28 ]]></programlisting>
  29         </example>
  30
  31         <note>
  32             <title>Differences in calling</title>
  33
  34             <para>
  35                 <classname>Zend_Rest_Client</classname> attempts to make remote methods
  36                 look as much like native methods as possible, the only
  37                 difference being that you must follow the method call with one
  38                 of either <methodname>get()</methodname>, <methodname>post()</methodname>,
  39                 <methodname>put()</methodname> or <methodname>delete()</methodname>. This call may
  40                 be made via method chaining or in separate method calls:
  41             </para>
  42
  43             <programlisting language="php"><![CDATA[
  44 $client->sayHello('Davey', 'Day');
  45 echo $client->get();
  46 ]]></programlisting>
  47         </note>
  48     </sect2>
  49
  50     <sect2 id="zend.rest.client.return">
  51         <title>Responses</title>
  52
  53         <para>
  54             All requests made using <classname>Zend_Rest_Client</classname> return a
  55             <classname>Zend_Rest_Client_Response</classname> object. This object has many
  56             properties that make it easier to access the results.
  57         </para>
  58
  59         <para>
  60             When the service is based on <classname>Zend_Rest_Server</classname>,
  61             <classname>Zend_Rest_Client</classname> can make several assumptions about the
  62             response, including response status (success or failure) and return
  63             type.
  64         </para>
  65
  66         <example id="zend.rest.client.return.example-1">
  67             <title>Response Status</title>
  68
  69             <programlisting language="php"><![CDATA[
  70 $result = $client->sayHello('Davey', 'Day')->get();
  71
  72 if ($result->isSuccess()) {
  73     echo $result; // "Hello Davey, Good Day"
  74 }
  75 ]]></programlisting>
  76         </example>
  77
  78         <para>
  79             In the example above, you can see that we use the request result as
  80             an object, to call <methodname>isSuccess()</methodname>, and then because of
  81             <methodname>__toString()</methodname>, we can simply <code>echo</code> the
  82             object to get the result. <classname>Zend_Rest_Client_Response</classname>
  83             will allow you to echo any scalar value. For complex types, you can
  84             use either array or object notation.
  85         </para>
  86
  87         <para>
  88             If however, you wish to query a service not using
  89             <classname>Zend_Rest_Server</classname> the
  90             <classname>Zend_Rest_Client_Response</classname> object will behave more like
  91             a <code>SimpleXMLElement</code>. However, to make things easier, it
  92             will automatically query the <acronym>XML</acronym> using XPath if the property is not
  93             a direct descendant of the document root element. Additionally, if
  94             you access a property as a method, you will receive the <acronym>PHP</acronym> value
  95             for the object, or an array of <acronym>PHP</acronym> value results.
  96         </para>
  97
  98         <example id="zend.rest.client.return.example-2">
  99             <title>Using Technorati's Rest Service</title>
 100
 101             <programlisting language="php"><![CDATA[
 102 $technorati = new Zend_Rest_Client('http://api.technorati.com/bloginfo');
 103 $technorati->key($key);
 104 $technorati->url('http://pixelated-dreams.com');
 105 $result = $technorati->get();
 106 echo $result->firstname() .' '. $result->lastname();
 107 ]]></programlisting>
 108         </example>
 109
 110         <example id="zend.rest.client.return.example-3">
 111             <title>Example Technorati Response</title>
 112
 113             <programlisting language="xml"><![CDATA[
 114 <?xml version="1.0" encoding="utf-8"?>
 115 <!-- generator="Technorati API version 1.0 /bloginfo" -->
 116 <!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN"
 117                       "http://api.technorati.com/dtd/tapi-002.xml">
 118 <tapi version="1.0">
 119     <document>
 120         <result>
 121             <url>http://pixelated-dreams.com</url>
 122             <weblog>
 123                 <name>Pixelated Dreams</name>
 124                 <url>http://pixelated-dreams.com</url>
 125                 <author>
 126                     <username>DShafik</username>
 127                     <firstname>Davey</firstname>
 128                     <lastname>Shafik</lastname>
 129                 </author>
 130                 <rssurl>
 131                     http://pixelated-dreams.com/feeds/index.rss2
 132                 </rssurl>
 133                 <atomurl>
 134                     http://pixelated-dreams.com/feeds/atom.xml
 135                 </atomurl>
 136                 <inboundblogs>44</inboundblogs>
 137                 <inboundlinks>218</inboundlinks>
 138                 <lastupdate>2006-04-26 04:36:36 GMT</lastupdate>
 139                 <rank>60635</rank>
 140             </weblog>
 141             <inboundblogs>44</inboundblogs>
 142             <inboundlinks>218</inboundlinks>
 143         </result>
 144     </document>
 145 </tapi>
 146 ]]></programlisting>
 147         </example>
 148
 149         <para>
 150             Here we are accessing the <code>firstname</code> and
 151             <code>lastname</code> properties. Even though these are not
 152             top-level elements, they are automatically returned when accessed by
 153             name.
 154         </para>
 155
 156         <note>
 157             <title>Multiple items</title>
 158
 159             <para>
 160                 If multiple items are found when accessing a value by name, an
 161                 array of SimpleXMLElements will be returned; accessing via
 162                 method notation will return an array of <acronym>PHP</acronym> values.
 163             </para>
 164         </note>
 165     </sect2>
 166
 167     <sect2 id="zend.rest.client.args">
 168         <title>Request Arguments</title>
 169
 170         <para>
 171             Unless you are making a request to a <classname>Zend_Rest_Server</classname>
 172             based service, chances are you will need to send multiple arguments
 173             with your request. This is done by calling a method with the name of
 174             the argument, passing in the value as the first (and only) argument.
 175             Each of these method calls returns the object itself, allowing for
 176             chaining, or "fluent" usage. The first call, or the first argument
 177             if you pass in more than one argument, is always assumed to be the
 178             method when calling a <classname>Zend_Rest_Server</classname> service.
 179         </para>
 180
 181         <example id="zend.rest.client.args.example-1">
 182             <title>Setting Request Arguments</title>
 183
 184             <programlisting language="php"><![CDATA[
 185 $client = new Zend_Rest_Client('http://example.org/rest');
 186
 187 $client->arg('value1');
 188 $client->arg2('value2');
 189 $client->get();
 190
 191 // or
 192
 193 $client->arg('value1')->arg2('value2')->get();
 194 ]]></programlisting>
 195         </example>
 196
 197         <para>
 198             Both of the methods in the example above, will result in the
 199             following get args:
 200             <code>?method=arg&amp;arg1=value1&amp;arg=value1&amp;arg2=value2</code>
 201         </para>
 202
 203         <para>
 204             You will notice that the first call of
 205             <code>$client->arg('value1');</code> resulted in both
 206             <code>method=arg&amp;arg1=value1</code> and <code>arg=value1</code>;
 207             this is so that <classname>Zend_Rest_Server</classname> can understand the
 208             request properly, rather than requiring pre-existing knowledge of
 209             the service.
 210         </para>
 211
 212         <warning>
 213             <title>Strictness of Zend_Rest_Client</title>
 214
 215             <para>
 216                 Any REST service that is strict about the arguments it receives will likely fail
 217                 using <classname>Zend_Rest_Client</classname>, because of the behavior described
 218                 above. This is not a common practice and should not cause problems.
 219             </para>
 220         </warning>
 221     </sect2>
 222 </sect1>
 223 <!--
 224 vim:se ts=4 sw=4 et:
 225 -->