documentation/manual/en/module_specs/Zend_Service_Nirvanix.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.nirvanix">
   4     <title>Zend_Service_Nirvanix</title>
   5
   6     <sect2 id="zend.service.nirvanix.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             Nirvanix provides an Internet Media File System (IMFS), an
  11             Internet storage service that allows applications to upload, store and
  12             organize files and subsequently access them using a standard Web
  13             Services interface. An IMFS is distributed clustered file system,
  14             accessed over the Internet, and optimized for dealing with media files
  15             (audio, video, etc). The goal of an IMFS is to provide massive
  16             scalability to deal with the challenges of media storage growth, with
  17             guaranteed access and availability regardless of time and location.
  18             Finally, an IMFS gives applications the ability to access data
  19             securely, without the large fixed costs associated with acquiring and
  20             maintaining physical storage assets.
  21         </para>
  22     </sect2>
  23
  24     <sect2 id="zend.service.nirvanix.registering">
  25         <title>Registering with Nirvanix</title>
  26
  27         <para>
  28             Before you can get started with <classname>Zend_Service_Nirvanix</classname>, you must
  29             first register for an account. Please see the
  30             <ulink url="http://www.nirvanix.com/gettingStarted.aspx">Getting Started</ulink>
  31             page on the Nirvanix website for more information.
  32         </para>
  33
  34         <para>
  35             After registering, you will receive a Username, Password, and Application Key.
  36             All three are required to use <classname>Zend_Service_Nirvanix</classname>.
  37         </para>
  38     </sect2>
  39
  40     <sect2 id="zend.service.nirvanix.apiDocumentation">
  41         <title>API Documentation</title>
  42
  43         <para>
  44             Access to the Nirvanix IMFS is available through both <acronym>SOAP</acronym> and a
  45             faster REST service. <classname>Zend_Service_Nirvanix</classname> provides a
  46             relatively thin <acronym>PHP</acronym> 5 wrapper around the REST service.
  47         </para>
  48
  49         <para>
  50             <classname>Zend_Service_Nirvanix</classname> aims to make using the Nirvanix REST
  51             service easier but understanding the service itself is still essential to be successful
  52             with Nirvanix.
  53         </para>
  54
  55         <para>
  56             The <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix
  57             <acronym>API</acronym> Documentation</ulink> provides an overview as well as detailed
  58             information using the service. Please familiarize yourself with this document and refer
  59             back to it as you use <classname>Zend_Service_Nirvanix</classname>.
  60         </para>
  61     </sect2>
  62
  63     <sect2 id="zend.service.nirvanix.features">
  64         <title>Features</title>
  65
  66         <para>
  67             Nirvanix's REST service can be used effectively with <acronym>PHP</acronym> using the
  68             <ulink url="http://www.php.net/simplexml">SimpleXML</ulink>
  69             extension and <classname>Zend_Http_Client</classname> alone. However, using it this way
  70             is somewhat inconvenient due to repetitive operations like passing the
  71             session token on every request and repeatedly checking the response body for
  72             error codes.
  73         </para>
  74
  75         <para>
  76             <classname>Zend_Service_Nirvanix</classname> provides the following functionality:
  77
  78             <itemizedlist>
  79                 <listitem>
  80                     <para>
  81                         A single point for configuring your Nirvanix authentication
  82                         credentials that can be used across the Nirvanix namespaces.
  83                     </para>
  84                 </listitem>
  85
  86                 <listitem>
  87                     <para>
  88                         A proxy object that is more convenient to use than an
  89                         <acronym>HTTP</acronym> client alone, mostly removing the need to manually
  90                         construct <acronym>HTTP</acronym> POST requests to access the REST service.
  91                     </para>
  92                 </listitem>
  93
  94                 <listitem>
  95                     <para>
  96                         A response wrapper that parses each response body and throws an
  97                         exception if an error occurred, alleviating the need to repeatedly
  98                         check the success of many commands.
  99                     </para>
 100                 </listitem>
 101
 102                 <listitem>
 103                     <para>
 104                         Additional convenience methods for some of the more common operations.
 105                     </para>
 106                 </listitem>
 107             </itemizedlist>
 108         </para>
 109     </sect2>
 110
 111     <sect2 id="zend.service.nirvanix.storing-your-first">
 112         <title>Getting Started</title>
 113
 114         <para>
 115             Once you have registered with Nirvanix, you're ready to store your first
 116             file on the IMFS. The most common operations that you will need to do
 117             on the IMFS are creating a new file, downloading an existing file, and
 118             deleting a file. <classname>Zend_Service_Nirvanix</classname> provides convenience
 119             methods for these three operations.
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 $auth = array('username' => 'your-username',
 124               'password' => 'your-password',
 125               'appKey'   => 'your-app-key');
 126
 127 $nirvanix = new Zend_Service_Nirvanix($auth);
 128 $imfs = $nirvanix->getService('IMFS');
 129
 130 $imfs->putContents('/foo.txt', 'contents to store');
 131
 132 echo $imfs->getContents('/foo.txt');
 133
 134 $imfs->unlink('/foo.txt');
 135 ]]></programlisting>
 136
 137         <para>
 138             The first step to using <classname>Zend_Service_Nirvanix</classname> is always
 139             to authenticate against the service. This is done by passing your
 140             credentials to the <classname>Zend_Service_Nirvanix</classname> constructor
 141             above. The associative array is passed directly to Nirvanix as POST
 142             parameters.
 143         </para>
 144
 145         <para>
 146             Nirvanix divides its web services into <ulink
 147                 url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999879">namespaces</ulink>.
 148             Each namespace encapsulates a group of related operations. After getting
 149             an instance of <classname>Zend_Service_Nirvanix</classname>, call the
 150             <methodname>getService()</methodname> method to create a proxy for the namespace
 151             you want to use. Above, a proxy for the <constant>IMFS</constant> namespace is created.
 152         </para>
 153
 154         <para>
 155             After you have a proxy for the namespace you want to use, call methods on it. The
 156             proxy will allow you to use any command available on the REST <acronym>API</acronym>.
 157             The proxy may also make convenience methods available, which wrap web service
 158             commands. The example above shows using the IMFS convenience methods to create a
 159             new file, retrieve and display that file, and finally delete the file.
 160         </para>
 161     </sect2>
 162
 163     <sect2 id="zend.service.nirvanix.understanding-proxy">
 164         <title>Understanding the Proxy</title>
 165
 166         <para>
 167             In the previous example, we used the <methodname>getService()</methodname> method to
 168             return a proxy object to the <constant>IMFS</constant> namespace. The proxy object
 169             allows you to use the Nirvanix REST service in a way that's closer to making a normal
 170             <acronym>PHP</acronym> method call, as opposed to constructing your own
 171             <acronym>HTTP</acronym> request objects.
 172         </para>
 173
 174         <para>
 175             A proxy object may provide convenience methods. These are methods that the
 176             <classname>Zend_Service_Nirvanix</classname> provides to simplify the use of
 177             the Nirvanix web services. In the previous example, the methods
 178             <methodname>putContents()</methodname>, <methodname>getContents()</methodname>, and
 179             <methodname>unlink()</methodname> do not have direct equivalents in the REST
 180             <acronym>API</acronym>. They are convenience methods provided by
 181             <classname>Zend_Service_Nirvanix</classname> that abstract more complicated operations
 182             on the REST <acronym>API</acronym>.
 183         </para>
 184
 185         <para>
 186             For all other method calls to the proxy object, the proxy will dynamically convert the
 187             method call to the equivalent <acronym>HTTP</acronym> POST request to the REST
 188             <acronym>API</acronym>. It does this by using the method name as the
 189             <acronym>API</acronym> command, and an associative array in the first argument as the
 190             POST parameters.
 191         </para>
 192
 193         <para>
 194             Let's say you want to call the REST <acronym>API</acronym> method <ulink
 195                 url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999923">RenameFile</ulink>,
 196             which does not have a convenience method in
 197             <classname>Zend_Service_Nirvanix</classname>:
 198         </para>
 199
 200         <programlisting language="php"><![CDATA[
 201 $auth = array('username' => 'your-username',
 202               'password' => 'your-password',
 203               'appKey'   => 'your-app-key');
 204
 205 $nirvanix = new Zend_Service_Nirvanix($auth);
 206 $imfs = $nirvanix->getService('IMFS');
 207
 208 $result = $imfs->renameFile(array('filePath' => '/path/to/foo.txt',
 209                                   'newFileName' => 'bar.txt'));
 210 ]]></programlisting>
 211
 212         <para>
 213             Above, a proxy for the <constant>IMFS</constant> namespace is created. A method,
 214             <methodname>renameFile()</methodname>, is then called on the proxy. This method does not
 215             exist as a convenience method in the <acronym>PHP</acronym> code, so it is trapped by
 216             <methodname>__call()</methodname> and converted into a POST request to the REST
 217             <acronym>API</acronym> where the associative array is used as the POST parameters.
 218         </para>
 219
 220         <para>
 221             Notice in the Nirvanix <acronym>API</acronym> documentation that
 222             <code>sessionToken</code> is required for this method but we did not give it to the
 223             proxy object. It is added automatically for your convenience.
 224         </para>
 225
 226         <para>
 227             The result of this operation will either be a
 228             <classname>Zend_Service_Nirvanix_Response</classname> object wrapping the
 229             <acronym>XML</acronym> returned by Nirvanix, or a
 230             <classname>Zend_Service_Nirvanix_Exception</classname> if an error occurred.
 231         </para>
 232     </sect2>
 233
 234     <sect2 id="zend.service.nirvanix.examining-results">
 235         <title>Examining Results</title>
 236
 237         <para>
 238             The Nirvanix REST <acronym>API</acronym> always returns its results in
 239             <acronym>XML</acronym>. <classname>Zend_Service_Nirvanix</classname> parses this
 240             <acronym>XML</acronym> with the <code>SimpleXML</code> extension and then decorates the
 241             resulting <code>SimpleXMLElement</code> with a
 242             <classname>Zend_Service_Nirvanix_Response</classname> object.
 243         </para>
 244
 245         <para>
 246             The simplest way to examine a result from the service is to use the
 247             built-in <acronym>PHP</acronym> functions like <methodname>print_r()</methodname>:
 248         </para>
 249
 250         <programlisting language="php"><![CDATA[
 251 <?php
 252 $auth = array('username' => 'your-username',
 253               'password' => 'your-password',
 254               'appKey'   => 'your-app-key');
 255
 256 $nirvanix = new Zend_Service_Nirvanix($auth);
 257 $imfs = $nirvanix->getService('IMFS');
 258
 259 $result = $imfs->putContents('/foo.txt', 'fourteen bytes');
 260 print_r($result);
 261 ?>
 262
 263 Zend_Service_Nirvanix_Response Object
 264 (
 265     [_sxml:protected] => SimpleXMLElement Object
 266         (
 267             [ResponseCode] => 0
 268             [FilesUploaded] => 1
 269             [BytesUploaded] => 14
 270         )
 271 )
 272 ]]></programlisting>
 273
 274         <para>
 275             You can access any property or method of the decorated <code>SimpleXMLElement</code>.
 276             In the above example, <code>$result->BytesUploaded</code> could be used to see the
 277             number of bytes received. Should you want to access the <code>SimpleXMLElement</code>
 278             directly, just use <code>$result->getSxml()</code>.
 279         </para>
 280
 281         <para>
 282             The most common response from Nirvanix is success (<code>ResponseCode</code> of zero).
 283             It is not normally necessary to check <code>ResponseCode</code> because any non-zero
 284             result will throw a <classname>Zend_Service_Nirvanix_Exception</classname>. See the next
 285             section on handling errors.
 286         </para>
 287     </sect2>
 288
 289     <sect2 id="zend.service.nirvanix.handling-errors">
 290         <title>Handling Errors</title>
 291
 292         <para>
 293             When using Nirvanix, it's important to anticipate errors that can be returned
 294             by the service and handle them appropriately.
 295         </para>
 296
 297         <para>
 298             All operations against the REST service result in an <acronym>XML</acronym> return
 299             payload that contains a <code>ResponseCode</code> element, such as the following
 300             example:
 301         </para>
 302
 303         <programlisting language="xml"><![CDATA[
 304 <Response>
 305    <ResponseCode>0</ResponseCode>
 306 </Response>
 307 ]]></programlisting>
 308
 309         <para>
 310             When the <code>ResponseCode</code> is zero such as in the example
 311             above, the operation was successful. When the operation is not
 312             successful, the <code>ResponseCode</code> is non-zero and an
 313             <code>ErrorMessage</code> element should be present.
 314         </para>
 315
 316         <para>
 317             To alleviate the need to repeatedly check if the <code>ResponseCode</code>
 318             is non-zero, <classname>Zend_Service_Nirvanix</classname> automatically checks each
 319             response returned by Nirvanix. If the <code>ResponseCode</code> indicates an
 320             error, a <classname>Zend_Service_Nirvanix_Exception</classname> will be thrown.
 321         </para>
 322
 323         <programlisting language="xml"><![CDATA[
 324 $auth = array('username' => 'your-username',
 325               'password' => 'your-password',
 326               'appKey'   => 'your-app-key');
 327 $nirvanix = new Zend_Service_Nirvanix($auth);
 328
 329 try {
 330
 331   $imfs = $nirvanix->getService('IMFS');
 332   $imfs->unlink('/a-nonexistant-path');
 333
 334 } catch (Zend_Service_Nirvanix_Exception $e) {
 335   echo $e->getMessage() . "\n";
 336   echo $e->getCode();
 337 }
 338 ]]></programlisting>
 339
 340         <para>
 341             In the example above, <methodname>unlink()</methodname> is a convenience method that
 342             wraps the <code>DeleteFiles</code> command on the REST <acronym>API</acronym>. The
 343             <code>filePath</code> parameter required by the <ulink
 344                 url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999918">DeleteFiles</ulink>
 345             command contains a path that does not exist. This will result in a
 346             <classname>Zend_Service_Nirvanix</classname> exception being thrown with the message
 347             "Invalid path" and code 70005.
 348         </para>
 349
 350         <para>
 351             The <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix
 352             <acronym>API</acronym> Documentation</ulink> describes the errors associated with each
 353             command. Depending on your needs, you may wrap each command in a <code>try</code> block
 354             or wrap many commands in the same <code>try</code> block for convenience.
 355         </para>
 356     </sect2>
 357 </sect1>