Contentful SDK v0.4.1
Contentful SDK

Contentful.Delivery (Contentful SDK v0.4.1) 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

Link to this section Summary

Functions

build_error()

Used to make a generic error, in case the API Response is not what is expected

build_error(response)

Used for the rate limit exceeded error, as it gives the user extra information on wait times

build_error(response_body, status)

Used to construct generic errors for calls against the CDA

json_library()

Gets the json library for the Contentful Delivery API based on the config/config.exs.

parse_response(arg, callback)

catch_all for any errors during flight (connection loss, etc.)

send_request(arg)

Sends a request against the CDA. It's really just a wrapper around HTTPoison.get/2

url()

constructs the base url with protocol for the CDA

url(space)

constructs the base url with the extension for a given space

url(space, env)

constructs the base url for the delivery endpoint for a given space and environment

Link to this section Functions

Link to this function

build_error()

View Source

Specs

build_error() :: {:error, :unknown}

Used to make a generic error, in case the API Response is not what is expected

Link to this function

build_error(response)

View Source

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

Link to this function

build_error(response_body, status)

View Source

Specs

build_error(String.t(), atom()) ::
  {:error, atom(), [{:original_message, String.t()}]}

Used to construct generic errors for calls against the CDA

Link to this function

json_library()

View Source

Specs

json_library() :: module()

Gets the json library for the Contentful Delivery API based on the config/config.exs.

Link to this function

parse_response(arg, callback)

View Source

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.)

Link to this function

send_request(arg)

View Source

Specs

send_request({binary(), any()}) ::
  {:error, HTTPoison.Error.t()} | {:ok, HTTPoison.Response.t()}

Sends a request against the CDA. It's really just a wrapper around HTTPoison.get/2

Link to this function

url()

View Source

Specs

url() :: String.t()

constructs the base url with protocol for the CDA

Examples 

"https://cdn.contentful.com" = url()
Link to this function

url(space)

View Source

Specs

url(nil) :: String.t()
url(String.t()) :: String.t()

constructs the base url with the extension for a given space

Examples 

"https://cdn.contentful.com/spaces/foo" = url("foo")
Link to this function

url(space, env)

View Source

Specs

url(String.t(), nil) :: String.t()

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")