Cloudflare.NET.Api 1.0.0

Cloudflare.NET SDK

This is an unofficial .NET SDK for the Cloudflare API. Its primary goal is to provide a strongly-typed, testable, and maintainable library for interacting with various Cloudflare services. The core SDK is lean and focuses on the REST API, while optional functionality, like the Analytics GraphQL API, is provided in a separate extension package.

1. Installation

The SDK is split into two packages. Install the one(s) you need from NuGet.

Core REST API Client (Required):

Install-Package Cloudflare.NET

R2 S3-Compatible Client (Optional):

Install-Package Cloudflare.NET.R2

Analytics GraphQL Client (Optional):

Install-Package Cloudflare.NET.Analytics

2. Quick Start

2.1 Configuration

First, configure your secrets in appsettings.json or through user secrets / environment variables.

{
  "Cloudflare": {
    "ApiToken": "your-cloudflare-api-token",
    "AccountId": "your-cloudflare-account-id",
    "ZoneId": "your-zone-id-for-testing-or-ops",
    // Optional
    "DefaultTimeout": "00:00:30",
    "RateLimiting": {
      "IsEnabled": true,
      "MaxRetries": 3,
      "PermitLimit": 25,
      "QueueLimit": 10
    }
  }
}

2.2 Dependency Injection

Register the client(s) in your Program.cs or Startup.cs.

var builder = WebApplication.CreateBuilder(args);

// 1. Register the core REST API client
builder.Services.AddCloudflareApiClient(builder.Configuration);

// 2. (Optional) Register the R2 client for object storage
builder.Services.AddCloudflareR2Client(builder.Configuration);

// 3. (Optional) Register the Analytics GraphQL client
builder.Services.AddCloudflareAnalytics();

2.3 Usage Example

Inject the client interfaces and use them in your services.

public class MyCloudflareService(ICloudflareApiClient cf, IAnalyticsApi analytics)
{
    // Example: Using the REST API client to manage DNS
    public async Task<DnsRecord?> FindDnsRecordAsync(string zoneId, string hostname)
    {
        // Use the strongly-typed Zones API
        return await cf.Zones.FindDnsRecordByNameAsync(zoneId, hostname);
    }

    // Example: Using the GraphQL client to get R2 analytics
    public async Task<long> GetTotalR2ObjectCountAsync(string accountId)
    {
        var request = new GraphQLRequest
        {
            Query = @"
                query GetStorage($account: String!) {
                    viewer {
                        accounts(filter: { accountTag: $account }) {
                            r2StorageAdaptiveGroups(limit: 1) {
                                max { objectCount }
                            }
                        }
                    }
                }",
            Variables = new { account = accountId }
        };

        // Send the query and get back a strongly-typed response model
        var response = await analytics.SendQueryAsync<GraphQLResponse>(request);
        
        return response.Accounts.FirstOrDefault()?
            .Storage.FirstOrDefault()?
            .Max?.ObjectCount ?? 0;
    }
}

3. API Coverage & Roadmap

3.1 Implemented API Resources

3.2 Planned API Resources (Roadmap)

The following API surfaces are planned for implementation to support advanced use cases.

4. API Token Permissions

To adhere to the principle of least privilege, create a Cloudflare API token with only the scopes your application requires.

Note: The R2 S3-compatible client (Cloudflare.NET.R2) does not use an API token; it requires separate R2 credentials (Access Key ID and Secret). The permissions below apply to the REST and GraphQL APIs.

CI/CD Token Tip: For running this repository's integration tests, your CI token needs Workers R2 Storage Write and Zone DNS Write to create and tear down test resources.