View Source Contentful.Delivery (Contentful SDK v0.6.0)
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
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_oneRetrieving 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_allYou 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_allFetching 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
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
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
Constructs a new Tesla client for requests.
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.)
Sends a request against the CDA. It's really just a wrapper around Tesla.get/3
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
@spec build_error() :: {:error, :unknown}
Used to make a generic error, in case the API Response is not what is expected
@spec build_error(Tesla.Env.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
Used to construct generic errors for calls against the CDA
@spec client() :: Tesla.Client.t()
Constructs a new Tesla client for requests.
Can be overridden with a custom client:
# config/config.exs
config :contentful, client: MyApp.CustomClient@spec json_library() :: module()
Gets the json library for the Contentful Delivery API based on the config/config.exs.
@spec parse_response( {:ok, Tesla.Env.t()}, (... -> any()) ) :: {:ok, struct()} | {:ok, [struct()], [{:total, non_neg_integer()}]} | {:error, :rate_limit_exceeded, [{:wait_for, integer()}]} | {:error, atom(), [{:original_message, String.t()}]}
@spec parse_response( {:error, any()}, (... -> any()) ) :: {:error, :unknown}
catch_all for any errors during flight (connection loss, etc.)
@spec send_request({binary(), any()}) :: Tesla.Env.result()
Sends a request against the CDA. It's really just a wrapper around Tesla.get/3
@spec url() :: String.t()
constructs the base url with protocol for the CDA
examples
Examples
"https://cdn.contentful.com" = url()constructs the base url with the extension for a given space
examples
Examples
"https://cdn.contentful.com/spaces/foo" = url("foo")constructs the base url for the delivery endpoint for a given space and environment
examples
Examples
"https://cdn.contentful.com/spaces/foo/environments/bar" = url("foo", "bar")