CloudflareApi

cloudflare_api is a thin Elixir wrapper around the Cloudflare Client API v4, focused on keeping you close to the underlying REST endpoints while providing a small set of ergonomic helpers.

Rate-limit retries

To automatically retry HTTP 429 responses, build your client with rate_limit_retry: true (or pass retry options):

client = CloudflareApi.new("api-token", rate_limit_retry: [max_retries: 2])
{:ok, zones} = CloudflareApi.Zones.list(client)

You can also wrap a single request with CloudflareApi.RateLimitRetry.run/2 and customize max_retries, base_backoff, or the sleep callback for tests.

The library currently includes convenience modules for:

Recent work is expanding coverage to additional endpoints using the same hand-written approach. Newly added modules include:

An up-to-date OpenAPI schema for the Cloudflare API is cached locally at priv/cloudflare_api/openapi.json and used to align request/response shapes.

NOTE: This library is still evolving and does not yet cover every Cloudflare endpoint. It aims to stay close to the official API and avoid heavy abstraction.

Installation

Add cloudflare_api to your mix.exs:

def deps do
  [
    {:cloudflare_api, "~> 0.6.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Supported Elixir / OTP

The project targets Elixir ~> 1.12 and above, and a reasonably recent OTP release. If you are on a newer Elixir (1.13+), it should work as long as your OTP version is supported by that Elixir release.

Getting Started

Configure your Cloudflare API token via an environment variable (recommended):

export CLOUDFLARE_API_TOKEN="your-cloudflare-api-token"

Create a client and list zones:

iex> client = CloudflareApi.client(System.fetch_env!("CLOUDFLARE_API_TOKEN"))
iex> {:ok, zones} = CloudflareApi.Zones.list(client, nil)
iex> Enum.map(zones, & &1["name"])
["example.com", "another.example.com"]

Work with DNS records:

# List DNS records for a zone
iex> zone_id = "your-zone-id"
iex> {:ok, records} = CloudflareApi.DnsRecords.list(client, zone_id, name: "www.example.com")

# Create a new A record
iex> {:ok, record} =
...>   CloudflareApi.DnsRecords.create(
...>     client,
...>     zone_id,
...>     "www.example.com",
...>     "203.0.113.10"
...>   )

# Update an existing record
iex> {:ok, updated} =
...>   CloudflareApi.DnsRecords.update(
...>     client,
...>     zone_id,
...>     record.id,
...>     record.hostname,
...>     "203.0.113.11"
...>   )

# Delete a record
iex> CloudflareApi.DnsRecords.delete(client, zone_id, record.id)
{:ok, "record-id"}

Build & Development

Install dependencies:

mix deps.get

Compile:

mix compile

Start an interactive shell with the app loaded:

iex -S mix

Working with the OpenAPI spec

To refresh the vendored OpenAPI schema from the official Cloudflare repository:

mix fetch_openapi
# or explicitly:
mix cloudflare_api.fetch_openapi

This writes the schema to priv/cloudflare_api/openapi.json.

Testing & Quality Checks

Run the test suite:

mix test

Format the code (and verify formatting):

mix format
mix format --check-formatted

Run Credo (static analysis) in dev or test:

mix credo

Run Dialyzer (if you have PLT caches set up):

mix dialyzer --plt          # If haven't run before or after changes
mix dialyzer --plt --force  # After changing Elixir/OTP versions or dependencies
mix dialyzer

Generate docs:

mix docs

Contributing

Contributions are welcome. Before opening a pull request:

Publishing to Hex.pm

These are general steps for publishing cloudflare_api to hex.pm. You only need to do this if you are a maintainer with publishing rights.

  1. Ensure Hex tooling is installed

    mix local.hex
mix local.rebar

  2. Bump the version

    • Update @version in mix.exs.
    • Update any version references in README.md (Installation section).
    • Optionally add or update a CHANGELOG entry.

  3. Run checks

    mix deps.get
mix test
mix credo
MIX_ENV=dev mix dialyzer     # optional but recommended
mix docs

  4. Build the Hex package

    mix hex.build

  5. Authenticate with Hex (first time only)

    mix hex.user register   # or: mix hex.user auth

  6. Publish to Hex

    mix hex.publish
# Answer the prompts to confirm publishing

  7. Tag and push the release (optional but recommended)

    git tag v0.2.4          # example
git push origin v0.2.4

Once published, docs will be available at:

https://hexdocs.pm/cloudflare_api

and the package page at:

https://hex.pm/packages/cloudflare_api

Security Notes