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

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

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

collection_query_params(options)

View Source

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

config(atom()) :: any()

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.

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

request_headers(api_key)

View Source

Specs

request_headers(String.t()) :: keyword()

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

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

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