documentation/manual/en/module_specs/Zend_Rest_Server.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.rest.server">
   4     <title>Zend_Rest_Server</title>
   5
   6     <sect2 id="zend.rest.server.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Rest_Server</classname> is intended as a fully-featured REST server.
  11         </para>
  12     </sect2>
  13
  14     <sect2 id="zend.rest.server.usage">
  15         <title>REST Server Usage</title>
  16
  17         <example id="zend.rest.server.usage.example-1">
  18             <title>Basic Zend_Rest_Server Usage - Classes</title>
  19
  20             <programlisting language="php"><![CDATA[
  21 $server = new Zend_Rest_Server();
  22 $server->setClass('My_Service_Class');
  23 $server->handle();
  24 ]]></programlisting>
  25         </example>
  26
  27         <example id="zend.rest.server.usage.example-2">
  28             <title>Basic Zend_Rest_Server Usage - Functions</title>
  29
  30             <programlisting language="php"><![CDATA[
  31 /**
  32  * Say Hello
  33  *
  34  * @param string $who
  35  * @param string $when
  36  * @return string
  37  */
  38 function sayHello($who, $when)
  39 {
  40     return "Hello $who, Good $when";
  41 }
  42
  43 $server = new Zend_Rest_Server();
  44 $server->addFunction('sayHello');
  45 $server->handle();
  46 ]]></programlisting>
  47         </example>
  48     </sect2>
  49
  50     <sect2 id="zend.rest.server.args">
  51         <title>Calling a Zend_Rest_Server Service</title>
  52
  53         <para>
  54             To call a <classname>Zend_Rest_Server</classname> service, you must supply a
  55             GET/POST <code>method</code> argument with a value that is the
  56             method you wish to call. You can then follow that up with any number
  57             of arguments using either the name of the argument (i.e. "who") or
  58             using <code>arg</code> following by the numeric position of the
  59             argument (i.e. "arg1").
  60         </para>
  61
  62         <note>
  63             <title>Numeric index</title>
  64
  65             <para>
  66                 Numeric arguments use a 1-based index.
  67             </para>
  68         </note>
  69
  70         <para>
  71             To call <code>sayHello</code> from the example above, you can use either:
  72         </para>
  73
  74         <para>
  75             <code>?method=sayHello&amp;who=Davey&amp;when=Day</code>
  76         </para>
  77
  78         <para>
  79             or:
  80         </para>
  81
  82         <para>
  83             <code>?method=sayHello&amp;arg1=Davey&amp;arg2=Day</code>
  84         </para>
  85     </sect2>
  86
  87     <sect2 id="zend.rest.server.customstatus">
  88         <title>Sending A Custom Status</title>
  89
  90         <para>
  91             When returning values, to return a custom status, you may return an
  92             array with a <code>status</code> key.
  93         </para>
  94
  95         <example id="zend.rest.server.customstatus.example-1">
  96             <title>Returning Custom Status</title>
  97
  98             <programlisting language="php"><![CDATA[
  99 /**
 100  * Say Hello
 101  *
 102  * @param string $who
 103  * @param string $when
 104  * @return array
 105  */
 106 function sayHello($who, $when)
 107 {
 108     return array('msg' => "An Error Occurred", 'status' => false);
 109 }
 110
 111 $server = new Zend_Rest_Server();
 112 $server->addFunction('sayHello');
 113 $server->handle();
 114 ]]></programlisting>
 115         </example>
 116     </sect2>
 117
 118     <sect2 id="zend.rest.server.customxml">
 119         <title>Returning Custom XML Responses</title>
 120
 121         <para>
 122             If you wish to return custom <acronym>XML</acronym>, simply return a
 123             <code>DOMDocument</code>, <code>DOMElement</code> or
 124             <code>SimpleXMLElement</code> object.
 125         </para>
 126
 127         <example id="zend.rest.server.customxml.example-1">
 128             <title>Return Custom XML</title>
 129
 130             <programlisting language="php"><![CDATA[
 131 /**
 132  * Say Hello
 133  *
 134  * @param string $who
 135  * @param string $when
 136  * @return SimpleXMLElement
 137  */
 138 function sayHello($who, $when)
 139 {
 140     $xml ='<?xml version="1.0" encoding="ISO-8859-1"?>
 141 <mysite>
 142     <value>Hey $who! Hope you\'re having a good $when</value>
 143     <code>200</code>
 144 </mysite>';
 145
 146     $xml = simplexml_load_string($xml);
 147     return $xml;
 148 }
 149
 150 $server = new Zend_Rest_Server();
 151 $server->addFunction('sayHello');
 152
 153 $server->handle();
 154 ]]></programlisting>
 155         </example>
 156
 157         <para>
 158             The response from the service will be returned without modification
 159             to the client.
 160         </para>
 161     </sect2>
 162 </sect1>
 163 <!--
 164 vim:se ts=4 sw=4 et:
 165 -->