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