ExAirtable.Service (ExAirtable v0.2.9) View Source

The Service defines methods to directly hit the Airtable API.

Most methods take an Airtable.Config.Table{}, along with parameters to be forwarded to the REST API.

These methods can be called directly, provided you have a valid %ExAirtable.Config.Table{} configuration. Alternatively, you can define a module that "inherits" this behavior - see ExAirtable.Table for more details.

API results will be returned in ExAirtable.Airtable.List{} and ExAirtable.Airtable.Record{} structs, to match what the Airtable API returns.

Examples

iex> table = %ExAirtable.Config.Table{
  base: %ExAirtable.Config.Base{
    id: "your base ID",
    api_key: "your api key"
  },
  name: "My Airtable Table Name"
} 
iex> list(table)
%Airtable.List{}

iex> retrieve(table, "rec1234")
%Airtable.Record{}

Link to this section Summary

Types

body()

headers()

method()

options()

params()

request()

url()

Functions

create(table, list)

Create a record in Airtable. Pass in a valid %ExAirtable.Airtable.List{} struct.

delete(table, id)

Delete a single record (by ID) from an Airtable.

delete(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url.

delete!(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url, raising an exception in case of failure.

get(url, headers \\ [], options \\ [])

Issues a GET request to the given url.

get!(url, headers \\ [], options \\ [])

Issues a GET request to the given url, raising an exception in case of failure.

head(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url.

head!(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url, raising an exception in case of failure.

list(table, opts \\ [])

List all records in a table.

list_async(table, opts \\ [])

Similar to list/2, except results aren't automatically concatenated with multiple API requests.

options(url, headers \\ [], options \\ [])

Issues an OPTIONS request to the given url.

options!(url, headers \\ [], options \\ [])

Issues a OPTIONS request to the given url, raising an exception in case of failure.

patch(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url.

patch!(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url, raising an exception in case of failure.

post(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url.

post!(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url, raising an exception in case of failure.

process_headers(headers) deprecated

Callback implementation for HTTPoison.Base.process_headers/1.

process_request_body(body)

Callback implementation for HTTPoison.Base.process_request_body/1.

process_request_headers(headers)

Callback implementation for HTTPoison.Base.process_request_headers/1.

process_request_options(options)

Callback implementation for HTTPoison.Base.process_request_options/1.

process_request_params(params)

Callback implementation for HTTPoison.Base.process_request_params/1.

process_request_url(url)

Callback implementation for HTTPoison.Base.process_request_url/1.

process_response(response)

Callback implementation for HTTPoison.Base.process_response/1.

process_response_body(body)

Callback implementation for HTTPoison.Base.process_response_body/1.

process_response_chunk(chunk)

Callback implementation for HTTPoison.Base.process_response_chunk/1.

process_response_headers(headers)

Callback implementation for HTTPoison.Base.process_response_headers/1.

process_response_status_code(status_code)

Callback implementation for HTTPoison.Base.process_response_status_code/1.

process_status_code(status_code) deprecated

Callback implementation for HTTPoison.Base.process_status_code/1.

process_url(url) deprecated

Callback implementation for HTTPoison.Base.process_url/1.

put(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url.

put!(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url, raising an exception in case of failure.

request(request)

Issues an HTTP request using a Request struct.

request(method, url, body \\ "", headers \\ [], options \\ [])

Issues an HTTP request with the given method to the given url.

request!(method, url, body \\ "", headers \\ [], options \\ [])

Issues an HTTP request with the given method to the given url, raising an exception in case of failure.

retrieve(table, id)

Retrieve a single record, matching by ID.

start()

Starts HTTPoison and its dependencies.

stream_next(resp)

Requests the next message to be streamed for a given HTTPoison.AsyncResponse.

update(table, list, opts \\ [])

Update a List{} of Record{}s in Airtable.

Link to this section Types

body()

Specs

body() :: HTTPoison.Base.body()

headers()

Specs

headers() :: HTTPoison.Base.headers()

method()

Specs

method() :: HTTPoison.Base.method()

options()

Specs

options() :: HTTPoison.Base.options()

params()

Specs

params() :: HTTPoison.Base.params()

request()

Specs

request() :: HTTPoison.Base.request()

url()

Specs

url() :: HTTPoison.Base.url()

Link to this section Functions

create(table, list)

Create a record in Airtable. Pass in a valid %ExAirtable.Airtable.List{} struct.

Returns an %ExAirtable.Airtable.List{} on success.

Example

iex> create(table, %List{})
%List{}

iex> create(table, list_with_errors)
{:error, reason}

delete(table, id)

Delete a single record (by ID) from an Airtable.

Returns a custom map on success - see below.

Example

iex> delete(table, "recJmmAR0IzpaekBn")
%{"deleted" => true, "id" => "recJmmAR0IzpaekBn"}

delete(url, headers \\ [], options \\ [])

Specs

delete(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a DELETE request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

delete!(url, headers \\ [], options \\ [])

Specs

delete!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a DELETE request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

get(url, headers \\ [], options \\ [])

Specs

get(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a GET request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

get!(url, headers \\ [], options \\ [])

Specs

get!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a GET request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

head(url, headers \\ [], options \\ [])

Specs

head(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a HEAD request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

head!(url, headers \\ [], options \\ [])

Specs

head!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a HEAD request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

list(table, opts \\ [])

List all records in a table.

Returns an %Airtable.List{} on success, and an {:error, reason} tuple on failure.

Valid options are:

params - any parameters you wish to send along to the Airtable API (for example view: "My View" or sort: "My Field". These should be sent as a Keyword list (see below). See https://airtable.com/YOURBASEID/api/docs for details (in the "List Records" sections).

Examples

iex> list(table, params: [view: "My View Name"])
%Airtable.List{}

list_async(table, opts \\ [])

Similar to list/2, except results aren't automatically concatenated with multiple API requests.

This is typically utilized by cache processes rather than called by hand - although it could be used by hand if you only want one page of results.

options(url, headers \\ [], options \\ [])

Specs

options(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues an OPTIONS request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

options!(url, headers \\ [], options \\ [])

Specs

options!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a OPTIONS request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

patch(url, body, headers \\ [], options \\ [])

Specs

patch(binary(), any(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a PATCH request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

patch!(url, body, headers \\ [], options \\ [])

Specs

patch!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a PATCH request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

post(url, body, headers \\ [], options \\ [])

Specs

post(binary(), any(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a POST request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

post!(url, body, headers \\ [], options \\ [])

Specs

post!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a POST request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

process_headers(headers)

This function is deprecated. Use process_response_headers/1 instead.

Specs

process_headers(list()) :: any()

Callback implementation for HTTPoison.Base.process_headers/1.

process_request_body(body)

Specs

process_request_body(body()) :: body()

Callback implementation for HTTPoison.Base.process_request_body/1.

process_request_headers(headers)

Specs

process_request_headers(headers()) :: headers()

Callback implementation for HTTPoison.Base.process_request_headers/1.

process_request_options(options)

Specs

process_request_options(options()) :: options()

Callback implementation for HTTPoison.Base.process_request_options/1.

process_request_params(params)

Specs

process_request_params(params()) :: params()

Callback implementation for HTTPoison.Base.process_request_params/1.

process_request_url(url)

Specs

process_request_url(url()) :: url()

Callback implementation for HTTPoison.Base.process_request_url/1.

process_response(response)

Specs

process_response(HTTPoison.Base.response()) :: any()

Callback implementation for HTTPoison.Base.process_response/1.

process_response_body(body)

Specs

process_response_body(binary()) :: any()

Callback implementation for HTTPoison.Base.process_response_body/1.

process_response_chunk(chunk)

Specs

process_response_chunk(binary()) :: any()

Callback implementation for HTTPoison.Base.process_response_chunk/1.

process_response_headers(headers)

Specs

process_response_headers(list()) :: any()

Callback implementation for HTTPoison.Base.process_response_headers/1.

process_response_status_code(status_code)

Specs

process_response_status_code(integer()) :: any()

Callback implementation for HTTPoison.Base.process_response_status_code/1.

process_status_code(status_code)

This function is deprecated. Use process_response_status_code/1 instead.

Specs

process_status_code(integer()) :: any()

Callback implementation for HTTPoison.Base.process_status_code/1.

process_url(url)

This function is deprecated. Use process_request_url/1 instead.

Specs

process_url(url()) :: url()

Callback implementation for HTTPoison.Base.process_url/1.

put(url, body \\ "", headers \\ [], options \\ [])

Specs

put(binary(), any(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a PUT request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

put!(url, body \\ "", headers \\ [], options \\ [])

Specs

put!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a PUT request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

request(request)

Specs

request(HTTPoison.Request.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues an HTTP request using a Request struct.

This function returns {:ok, response} or {:ok, async_response} if the request is successful, {:error, reason} otherwise.

Examples

request = %HTTPoison.Request{
  method: :post,
  url: "https://my.website.com",
  body: "{\"foo\": 3}",
  headers: [{"Accept", "application/json"}]
}

request(request)

request(method, url, body \\ "", headers \\ [], options \\ [])

Specs

request(method(), binary(), any(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues an HTTP request with the given method to the given url.

This function is usually used indirectly by get/3, post/4, put/4, etc

Args:

method - HTTP method as an atom (:get, :head, :post, :put, :delete, etc.)
url - target url as a binary string or char list
body - request body. See more below
headers - HTTP headers as an orddict (e.g., [{"Accept", "application/json"}])
options - Keyword list of options

Body: see type HTTPoison.Request

Options: see type HTTPoison.Request

This function returns {:ok, response} or {:ok, async_response} if the request is successful, {:error, reason} otherwise.

Examples

request(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])

request!(method, url, body \\ "", headers \\ [], options \\ [])

Specs

request!(method(), binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues an HTTP request with the given method to the given url, raising an exception in case of failure.

request!/5 works exactly like request/5 but it returns just the response in case of a successful request, raising an exception in case the request fails.

retrieve(table, id)

Retrieve a single record, matching by ID.

Returns an %Airtable.Record{} on success and an {:error, reason} tuple on failure.

start()

Starts HTTPoison and its dependencies.

stream_next(resp)

Specs

stream_next(HTTPoison.AsyncResponse.t()) ::
  {:ok, HTTPoison.AsyncResponse.t()} | {:error, HTTPoison.Error.t()}

Requests the next message to be streamed for a given HTTPoison.AsyncResponse.

See request!/5 for more detailed information.

update(table, list, opts \\ [])

Update a List{} of Record{}s in Airtable.

Valid options include:

objectionable_fields - A list of field names to remove from the fields entry of any Record in your List. This is typically used if you're trying to update in a table that doesn't allow updating certain (calculated) fields.
overwrite - Will overwrite all values in the destination record with values being sent. Default is false, which will only update fields that have values (ie aren't null).