ExTwilio.Api
Provides a basic HTTP interface to allow easy communication with the Twilio API, by wrapping HTTPotion
.
Examples
Requests are made to the Twilio API by passing in a resource module into one of this Api
module's many functions. The correct URL to the resource is inferred from the module name.
ExTwilio.Api.all(Resource)
[%Resource{ ... }, %Resource{ ... }]
Items are returned as instances of the given module's struct. For more details, see the documentation for each function.
Summary↑
all(module, options \\ []) | Return all the resources available for a given Twilio resource |
create(module, data, options \\ []) | Create a new resource in the Twilio API |
delete(url, options \\ []) | |
destroy(module, sid, options \\ []) | Destroy an existing resource in the Twilio Api |
fetch_page(module, path, options \\ []) | Fetch a particular page of results from the API, using a page URL provided by Twilio in its pagination metadata |
find(module, sid, options \\ []) | Find a given resource in the Twilio API by its SID |
get(url, options \\ []) | |
handle_response(response) | |
head(url, options \\ []) | |
list(module, options \\ []) | Get the first page of results for a given resource. Page size is configurable with the |
options(url, options \\ []) | |
patch(url, options \\ []) | |
post(url, options \\ []) | |
process_arguments(method, url, options) | |
process_options(options) | Adds the Account SID and Auth Token to every request through HTTP basic auth |
process_request_body(body) | If the request body is a list, then convert the list to a query string. Otherwise, pass it through unmodified |
process_request_headers(headers) | Automatically add the Content-Type application/x-www-form-urlencoded. This allows POST request data to be processed properly. It seems to have no negative effect on GET calls, so it is added to all requests |
process_response_body(body) | |
process_response_chunk(chunk) | |
process_response_headers(headers) | |
process_status_code(status_code) | |
process_url(url) | |
put(url, options \\ []) | |
request(method, url, options \\ []) | Sends an HTTP request. Args: * method - HTTP method, atom (:get, :head, :post, :put, :delete, etc.) * url - URL, binary string or char list * options - orddict of options Options: * body - request body, binary string or char list * headers - HTTP headers, orddict (eg. ["Accept": "application/json"]) * timeout - timeout in ms, integer * basic_auth - basic auth credentials (eg. {"user", "password"}) * stream_to - if you want to make an async request, the pid of the process * direct - if you want to use ibrowse's direct feature, the pid of the worker spawned by spawn_worker_process or spawn_link_worker_process Returns HTTPotion.Response or HTTPotion.AsyncResponse if successful. Raises HTTPotion.HTTPError if failed |
request(method, url, body, headers, options) | Deprecated form of request; body and headers are now options, see request/3 |
request_direct(conn_pid, method, url, body \\ "", headers \\ [], options \\ []) | Deprecated form of request with the direct option; body and headers are now options, see request/3 |
spawn_link_worker_process(url, options \\ []) | |
spawn_worker_process(url, options \\ []) | |
start() | |
stop_worker_process(pid) | |
stream(module, options \\ []) | Seamlessly stream through all available pages of a resource with |
transformer(target) | |
update(module, sid, data, options \\ []) | Update an existing resource in the Twilio Api |
Functions
Specs:
- all(atom, list) :: [%{}]
Return all the resources available for a given Twilio resource.
Important: Since there may be many pages of results, this function has the potential to block your process for a long time. Therefore, be very careful. Whenever possible, you should use stream/2
or list/2
.
Examples
ExTwilio.Api.all(ExTwilio.Call)
[%Call{ ... }, %Call{ ... }, ...]
If you want the function to take less time, you can increase the size of the pages returned by Twilio. This will reduce the number of requests.
ExTwilio.Api.all(ExTwilio.Call, page_size: 100)
Specs:
- create(atom, list, list) :: ExTwilio.Parser.success | ExTwilio.Parser.error
Create a new resource in the Twilio API.
Examples
ExTwilio.Api.create(ExTwilio.Call, [to: "1112223333", from: "4445556666"])
{:ok, %Call{ ... }}
ExTwilio.Api.create(ExTwilio.Call, [])
{:error, "No 'To' number is specified", 400}
Destroy an existing resource in the Twilio Api.
Examples
ExTwilio.Api.destroy(ExTwilio.Call, "<sid>")
:ok
ExTwilio.Api.destroy(ExTwilio.Call, "nonexistent")
{:error, "The requested resource ... was not found", 404}
Specs:
- fetch_page(atom, String.t | nil, list) :: ExTwilio.Parser.success_list | ExTwilio.Parser.error
Fetch a particular page of results from the API, using a page URL provided by Twilio in its pagination metadata.
Example
{:ok, list, meta} = ExTwilio.Api.list(ExTwilio.Call)
{:ok, next_page, meta} = ExTwilio.Api.next_page(ExTwilio.Call, meta["next_page_uri"])
Specs:
- find(atom, String.t | nil, list) :: ExTwilio.Parser.success | ExTwilio.Parser.error
Find a given resource in the Twilio API by its SID.
Examples
ExTwilio.Api.find(ExTwilio.Call, "<sid here>")
{:ok, %Call{ ... }}
ExTwilio.Api.find(ExTwilio.Call, "nonexistent sid")
{:error, "The requested resource couldn't be found...", 404}
Specs:
- list(atom, list) :: ExTwilio.Parser.success_list | ExTwilio.Parser.error
Get the first page of results for a given resource. Page size is configurable with the page_size
option. For paging through multiple pages, see one of these functions:
fetch_page/2
all/0
stream/2
Examples
{:ok, list, meta} = ExTwilio.Api.list(ExTwilio.Call, page_size: 1)
Specs:
Specs:
- process_options(list) :: list
Adds the Account SID and Auth Token to every request through HTTP basic auth.
Example
iex> ExTwilio.Api.process_options([])
[basic_auth: { nil, nil }]
If the request body is a list, then convert the list to a query string. Otherwise, pass it through unmodified.
Examples
iex> ExTwilio.Api.process_request_body([hello: "world"])
"Hello=world"
iex> ExTwilio.Api.process_request_body("Hello, world!")
"Hello, world!"
Specs:
- process_request_headers(list) :: list
Automatically add the Content-Type application/x-www-form-urlencoded. This allows POST request data to be processed properly. It seems to have no negative effect on GET calls, so it is added to all requests.
Example
iex> ExTwilio.Api.process_request_headers([])
[{:"Content-Type", "application/x-www-form-urlencoded; charset=UTF-8"}]
Specs:
- request(atom, String.t, Dict.t) :: %HTTPotion.Response{body: term, headers: term, status_code: term} | %HTTPotion.AsyncResponse{id: term}
Sends an HTTP request. Args: * method - HTTP method, atom (:get, :head, :post, :put, :delete, etc.) * url - URL, binary string or char list * options - orddict of options Options: * body - request body, binary string or char list * headers - HTTP headers, orddict (eg. ["Accept": "application/json"]) * timeout - timeout in ms, integer * basic_auth - basic auth credentials (eg. {"user", "password"}) * stream_to - if you want to make an async request, the pid of the process * direct - if you want to use ibrowse's direct feature, the pid of the worker spawned by spawn_worker_process or spawn_link_worker_process Returns HTTPotion.Response or HTTPotion.AsyncResponse if successful. Raises HTTPotion.HTTPError if failed.
Deprecated form of request; body and headers are now options, see request/3.
Deprecated form of request with the direct option; body and headers are now options, see request/3.
Specs:
- stream(module, list) :: Enumerable.t
Seamlessly stream through all available pages of a resource with stream/2
. Pages will be requested lazily, allowing you to start processing as soon as the first page of results is returned.
Page size will affect the number of requests made to Twilio to get the entire collection, so it can be configured with the page_size
option.
Examples
stream = ExTwilio.Api.stream(ExTwilio.Call, page_size: 1)
Enum.each stream, fn(call) ->
IO.puts "We made a call to #{call.to}!"
end
# Collapse the stream into a list. List will not be returned until all
# pages have been fetched from Twilio.
Enum.into stream, []
[%Call{ ... }, %Call{ ... }, ...]
# Progressively build filters with the Pipe operator.
ExTwilio.Api.stream(ExTwilio.Call)
|> Stream.filter fn(call) -> call.duration > 120 end
|> Stream.map fn(call) -> call.sid end
|> Enum.into [] # Only here is the stream actually executed
Specs:
- update(atom, String.t, list, list) :: ExTwilio.Parser.success | ExTwilio.Parser.error
Update an existing resource in the Twilio Api.
Examples
ExTwilio.Api.update(ExTwilio.Call, "<sid>", [status: "canceled"])
{:ok, %Call{ status: "canceled" ... }}
ExTwilio.Api.update(ExTwilio.Call, "nonexistent", [status: "complete"])
{:error, "The requested resource ... was not found", 404}