mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-14 19:02:41 +01:00
98 lines
3 KiB
ReStructuredText
98 lines
3 KiB
ReStructuredText
.. _ref-rest:
|
|
|
|
==========================
|
|
Using the Twilio REST API
|
|
==========================
|
|
|
|
Since version 3.0, we've introduced an updated API for interacting with the
|
|
Twilio REST API. Gone are the days of manual URL creation and XML parsing.
|
|
|
|
Creating a REST Client
|
|
=======================
|
|
|
|
Before querying the API, you'll need to create a :php:class:`Services_Twilio`
|
|
instance. The constructor takes your Twilio Account Sid and Auth
|
|
Token (both available through your `Twilio Account Dashboard
|
|
<http:www.twilio.com/user/account>`_).
|
|
|
|
.. code-block:: php
|
|
|
|
$ACCOUNT_SID = "AC123";
|
|
$AUTH_TOKEN = "secret";
|
|
$client = new Services_Twilio($ACCOUNT_SID, $AUTH_TOKEN);
|
|
|
|
The :attr:`account` attribute
|
|
-----------------------------
|
|
|
|
You access the Twilio API resources through this :attr:`$client`,
|
|
specifically the :attr:`$account` attribute, which is an instance of
|
|
:php:class:`Services_Twilio_Rest_Account`. We'll use the `Calls resource
|
|
<http://www.twilio.com/docs/api/rest/call>`_ as an example.
|
|
|
|
Listing Resources
|
|
====================
|
|
|
|
Iterating over the :attr:`calls` attribute will iterate over all of your call
|
|
records, handling paging for you. Only use this when you need to get all your
|
|
records.
|
|
|
|
The :attr:`$call` object is a :php:class:`Services_Twilio_Rest_Call`, which
|
|
means you can easily access fields through it's properties. The attribute names
|
|
are lowercase and use underscores for sepearators. All the available attributes
|
|
are documented in the :doc:`/api/rest` documentation.
|
|
|
|
.. code-block:: php
|
|
|
|
// If you have many calls, this could take a while
|
|
foreach($client->account->calls as $call) {
|
|
print $call->price . '\n';
|
|
print $call->duration . '\n';
|
|
}
|
|
|
|
Filtering Resources
|
|
-------------------
|
|
|
|
Many Twilio list resources allow for filtering via :php:meth:`getIterator`
|
|
which takes an optional array of filter parameters. These parameters correspond
|
|
directlty to the listed query string parameters in the REST API documentation.
|
|
|
|
You can create a filtered iterator like this:
|
|
|
|
.. code-block:: php
|
|
|
|
$filteredCalls = $client->account->calls->getIterator(
|
|
0, 50, array("Status" => "in-progress"));
|
|
foreach($filteredCalls as $call) {
|
|
print $call->price . '\n';
|
|
print $call->duration . '\n';
|
|
}
|
|
|
|
Retrieving the Total Number of Resources
|
|
----------------------------------------
|
|
|
|
Each of the list resources supports the `Countable` interface, which means you
|
|
can retrieve the total number of list items like so:
|
|
|
|
.. code-block:: php
|
|
|
|
echo count($client->account->calls);
|
|
|
|
Getting a Specific Resource
|
|
=============================
|
|
|
|
If you know the unique identifier for a resource, you can get that resource
|
|
using the :php:meth:`get` method on the list resource.
|
|
|
|
.. code-block:: php
|
|
|
|
$call = $client->account->calls->get("CA123");
|
|
|
|
:php:meth:`get` fetches objects lazily, so it will only load a resource when it
|
|
is needed. This allows you to get nested objects without making multiple HTTP
|
|
requests.
|
|
|
|
.. code-block:: php
|
|
|
|
$participant = $client->account->conferences
|
|
->get("CO123")->participants->get("PF123");
|
|
|