Contentful SDK v0.3.2 Contentful.Delivery View Source
The Delivery API is the main access point for fetching data for your customers. The API is read only.
If you wish to manipulate data, please have a look at the Contentful.Management
.
Basic interaction
The space_id
, the environment
and your access_token
can all be configured in
config/config.exs
:
# config/config.exs
config :contentful, delivery: [
space_id: "<my_space_id>",
environment: "<my_environment>",
access_token: "<my_access_token_cda>"
]
The space can then be fetched as a Contentful.Space
via a simple query:
import Contentful.Query
alias Contentful.Delivery.Spaces
{:ok, space} = Spaces |> fetch_one
Retrieving items is then just a matter of importing Contentful.Query
:
import Contentful.Query
alias Contentful.Delivery.Entries
{:ok, entries, total: _total_count_of_entries} = Entries |> fetch_all
You can create query chains to form more complex queries:
import Contentful.Query
alias Contentful.Delivery.Entries
{:ok, entries, total: _total_count_of_entries} =
Entries
|> skip(2)
|> limit(10)
|> include(2)
|> fetch_all
Fetching indidvidual entities is straight forward:
import Contentful.Query
alias Contentful.Delivery.Assets
my_asset_id = "my_asset_id"
{:ok, assets, total: _total_count_of_assets} = Assets |> fetch_one(my_asset_id)
All query resolvers also support chaning the space_id
, environment
and access_token
at call
time:
import Contentful.Query
alias Contentful.Delivery.Assets
my_asset_id = "my_asset_id"
{:ok, asset} =
Assets
|> fetch_one(my_asset_id)
Note: If you want to pass the configuration at call time, you can pass these later as function parameters to the resolver call:
import Contentful.Query
alias Contentful.Delivery.Assets
my_asset_id = "my_asset_id"
my_space_id = "bmehzfuz4raf"
my_environment = "staging"
my_access_token = "not_a_real_token"
{:ok, asset} =
Assets
|> fetch_one(my_asset_id, my_space_id, my_environment, my_access_token)
# also works for fetch_all:
{:ok, assets, _} =
Assets
|> fetch_all(my_space_id, my_environment, my_access_token)
# and for stream:
[ asset | _ ] =
Assets
|> stream(my_space_id, my_environment, my_access_token)
|> Enum.to_list
Spaces as an exception
Unfortunately, Contentful.Delivery.Spaces
do not support complete collection behaviour:
# doesn't exist in the Delivery API:
{:error, _, _} = Contentful.Delivery.Spaces |> fetch_all
# however, you can still retrieve a single `Contentful.Space`:
{:ok, space} = Contentful.Delivery.Spaces |> fetch_one # the configured space
{:ok, my_space} = Contentful.Delivery.Spaces |> fetch_one("my_space_id") # a passed space
Further reading
- Contentful Delivery API docs (CDA).
Link to this section Summary
Functions
Used to make a generic error, in case the API Response is not what is expected
Used for the rate limit exceeded error, as it gives the user extra information on wait times
Used to construct generic errors for calls against the CDA
parses the options for retrieving a collection. It will drop any option that is not in @collection_filters ([:limit, :skip])
loads the configuration for the delivery module from the contentful app configuration
Can be used to retrieve configuration for the Contentful.Delivery
module
Gets the json library for the Contentful Delivery API based on the config/config.exs.
catch_all for any errors during flight (connection loss, etc.)
Builds the request headers for a request against the CDA, taking api access tokens into account
Sends a request against the CDA. It's really just a wrapper around HTTPoison.get/2
constructs the base url with protocol for the CDA
constructs the base url with the extension for a given space
constructs the base url for the delivery endpoint for a given space and environment
Link to this section Functions
Specs
build_error() :: {:error, :unknown}
Used to make a generic error, in case the API Response is not what is expected
Specs
build_error(HTTPoison.Response.t()) :: {:error, :rate_limit_exceeded, [{:wait_for, integer()}]}
Used for the rate limit exceeded error, as it gives the user extra information on wait times
Specs
Used to construct generic errors for calls against the CDA
Specs
collection_query_params( limit: pos_integer(), skip: non_neg_integer(), content_type: String.t(), include: non_neg_integer() ) :: String.t()
parses the options for retrieving a collection. It will drop any option that is not in @collection_filters ([:limit, :skip])
Examples
"?limit=50&skip=25&order=foobar"
= collection_query_params(limit: 50, baz: "foo", skip: 25, order: "foobar", bar: 42)
Specs
config() :: [keyword()]
loads the configuration for the delivery module from the contentful app configuration
Specs
Can be used to retrieve configuration for the Contentful.Delivery
module
Examples
config :contentful, delivery: [
my_config: "foobar"
]
"foobar" = Contentful.Delivery.config(:my_config)
Specs
json_library() :: module()
Gets the json library for the Contentful Delivery API based on the config/config.exs.
Specs
parse_response({:ok, HTTPoison.Response.t()}, (... -> any())) :: {:ok, struct()} | {:ok, [struct()], [{:total, non_neg_integer()}]} | {:error, :rate_limit_exceeded, [{:wait_for, integer()}]} | {:error, atom(), [{:original_message, String.t()}]}
parse_response({:error, any()}, (... -> any())) :: {:error, :unknown}
catch_all for any errors during flight (connection loss, etc.)
Specs
Builds the request headers for a request against the CDA, taking api access tokens into account
Examples
my_access_token = "foobarfoob4z"
[
"Authorization": "Bearer foobarfoob4z",
"User-Agent": "Contentful Elixir SDK",
"Accept": "application/json"
] = my_access_token |> request_headers()
Specs
send_request(tuple()) :: {:ok, HTTPoison.Response.t()}
Sends a request against the CDA. It's really just a wrapper around HTTPoison.get/2
Specs
url() :: String.t()
constructs the base url with protocol for the CDA
Examples
"https://cdn.contentful.com" = url()
Specs
constructs the base url with the extension for a given space
Examples
"https://cdn.contentful.com/spaces/foo" = url("foo")
Specs
constructs the base url for the delivery endpoint for a given space and environment
Examples
"https://cdn.contentful.com/spaces/foo/environments/bar" = url("foo", "bar")