[Summary view] [Print] [Text view]

   1  .. _ref-rest:
   2  
   3  ==========================
   4  Using the Twilio REST API
   5  ==========================
   6  
   7  Since version 3.0, we've introduced an updated API for interacting with the
   8  Twilio REST API. Gone are the days of manual URL creation and XML parsing.
   9  
  10  Creating a REST Client
  11  =======================
  12  
  13  Before querying the API, you'll need to create a :php:class:`Services_Twilio`
  14  instance. The constructor takes your Twilio Account Sid and Auth
  15  Token (both available through your `Twilio Account Dashboard
  16  <http:www.twilio.com/user/account>`_).
  17  
  18  .. code-block:: php
  19  
  20      $ACCOUNT_SID = "AC123";
  21      $AUTH_TOKEN = "secret";
  22      $client = new Services_Twilio($ACCOUNT_SID, $AUTH_TOKEN);
  23  
  24  The :attr:`account` attribute
  25  -----------------------------
  26  
  27  You access the Twilio API resources through this :attr:`$client`,
  28  specifically the :attr:`$account` attribute, which is an instance of
  29  :php:class:`Services_Twilio_Rest_Account`. We'll use the `Calls resource
  30  <http://www.twilio.com/docs/api/rest/call>`_ as an example.
  31  
  32  Listing Resources
  33  ====================
  34  
  35  Iterating over the :attr:`calls` attribute will iterate over all of your call
  36  records, handling paging for you. Only use this when you need to get all your
  37  records.
  38  
  39  The :attr:`$call` object is a :php:class:`Services_Twilio_Rest_Call`, which
  40  means you can easily access fields through it's properties. The attribute names
  41  are lowercase and use underscores for sepearators. All the available attributes
  42  are documented in the :doc:`/api/rest` documentation.
  43  
  44  .. code-block:: php
  45  
  46      // If you have many calls, this could take a while
  47      foreach($client->account->calls as $call) {
  48          print $call->price . '\n';
  49          print $call->duration . '\n';
  50      }
  51  
  52  Filtering Resources
  53  -------------------
  54  
  55  Many Twilio list resources allow for filtering via :php:meth:`getIterator`
  56  which takes an optional array of filter parameters. These parameters correspond
  57  directlty to the listed query string parameters in the REST API documentation.
  58  
  59  You can create a filtered iterator like this:
  60  
  61  .. code-block:: php
  62  
  63      $filteredCalls = $client->account->calls->getIterator(
  64          0, 50, array("Status" => "in-progress"));
  65      foreach($filteredCalls as $call) {
  66          print $call->price . '\n';
  67          print $call->duration . '\n';
  68      }
  69  
  70  Retrieving the Total Number of Resources
  71  ----------------------------------------
  72  
  73  Each of the list resources supports the `Countable` interface, which means you
  74  can retrieve the total number of list items like so:
  75  
  76  .. code-block:: php
  77  
  78      echo count($client->account->calls);
  79  
  80  Getting a Specific Resource
  81  =============================
  82  
  83  If you know the unique identifier for a resource, you can get that resource
  84  using the :php:meth:`get` method on the list resource.
  85  
  86  .. code-block:: php
  87  
  88      $call = $client->account->calls->get("CA123");
  89  
  90  :php:meth:`get` fetches objects lazily, so it will only load a resource when it
  91  is needed. This allows you to get nested objects without making multiple HTTP
  92  requests.
  93  
  94  .. code-block:: php
  95  
  96      $participant = $client->account->conferences
  97          ->get("CO123")->participants->get("PF123");
  98