CloudflareApi (cloudflare_api v0.5.0)

View Source

Top-level entry point for the Cloudflare API client.

CloudflareApi is a thin, explicit wrapper around the Cloudflare v4 API. It provides convenient functions and Elixir idioms so you don't have to work with raw HTTP requests by hand.

Status

Note: this package is under active development and may be refactored in substantive ways. If you need to get to production quickly, consider pinning to a specific version and watching the changelog.

Philosophy

This library assumes that a well-designed REST API does not need a heavy abstraction layer on top:

  • Request/response shapes stay close to the official Cloudflare JSON.
  • Functions generally return {:ok, result} / {:error, reason} tuples.
  • Modules and function names mirror Cloudflare's own endpoint groupings.

The upside is that you can keep the official Cloudflare documentation open alongside this library instead of learning a separate abstraction. The downside is that if you want to be fully shielded from the underlying API details, this probably is not the package for you.

Getting started

The usual way to use the library is:

token  = System.fetch_env!("CLOUDFLARE_API_TOKEN")
client = CloudflareApi.new(token)

{:ok, zones} = CloudflareApi.Zones.list(client)

or, using the zero-arity client function:

client_fun = CloudflareApi.client("api-token")
{:ok, records} = CloudflareApi.DnsRecords.list(client_fun, "zone-id", name: "www.example.com")

You may also wish to look through the Livebooks in livebooks/ for additional end-to-end examples.

Summary

Types

client()

A configured Tesla client or a zero-arity function that returns one.

error_reason()

Standard error reasons returned by this library when wrapping HTTP calls.

id()

Generic identifier helper for Cloudflare resource IDs.

options()

Common keyword or map options passed to Cloudflare endpoints.

result(result)

Helper type for {:ok, value} / {:error, reason} tuples.

Functions

client(cloudflare_api_token)

Build a reusable zero-arity client function.

new(cloudflare_api_token)

Build a Tesla.Client.t() configured for the Cloudflare v4 API.

Types

client()

@type client() :: Tesla.Client.t() | (-> Tesla.Client.t())

A configured Tesla client or a zero-arity function that returns one.

error_reason()

@type error_reason() ::
  Tesla.Env.t()
  | %Tesla.Error{
      __exception__: true,
      env: term(),
      reason: term(),
      stack: term()
    }
  | term()

Standard error reasons returned by this library when wrapping HTTP calls.

id()

@type id() :: String.t()

Generic identifier helper for Cloudflare resource IDs.

options()

@type options() :: keyword() | map() | nil

Common keyword or map options passed to Cloudflare endpoints.

result(result)

@type result(result) :: {:ok, result} | {:error, error_reason()}

Helper type for {:ok, value} / {:error, reason} tuples.

Functions

client(cloudflare_api_token)

@spec client(String.t()) :: term()

Build a reusable zero-arity client function.

This wraps new/1 and returns a function that, when called, yields a configured Tesla.Client.t(). It is convenient when you want to inject a "current Cloudflare client" into other modules without threading the %Tesla.Client{} struct manually.

  • cloudflare_api_token – a Cloudflare API token with the permissions your calls require

Examples

iex> client_fun = CloudflareApi.client("api-token")
iex> client1 = client_fun.()
iex> client2 = client_fun.()
iex> is_struct(client1, Tesla.Client) and client1 == client2
true

new(cloudflare_api_token)

@spec new(String.t()) :: term()

Build a Tesla.Client.t() configured for the Cloudflare v4 API.

The returned client can be passed to any of the CloudflareApi.* endpoint modules.

  • cloudflare_api_token – a Cloudflare API token with the permissions your calls require

Examples

iex> client = CloudflareApi.new("api-token")
iex> is_struct(client, Tesla.Client)
true