- query values (zone names, subdomains) are URL-encoded, zone and record IDs must be alphanumeric: prevents query parameter injection and path traversal - zone names and subdomains with whitespace, control characters or \ ? # & ; | < > " ' ` are rejected with an IllegalArgumentException - withBaseUrl only accepts HTTPS (plain HTTP only for loopback hosts), no query/fragment, trailing slash is removed - connect and response timeouts (defaults 10 s / 30 s), configurable via withConnectTimeout / withResponseTimeout; values below 1 ms or overflowing milliseconds are rejected - null credentials throw an IllegalArgumentException, build() without authentication an IllegalStateException - tests, README and changelog updated refs #2 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CloudflareDNS-java
Preface
This project provides a java client for minimalistic access to the Cloudflare API version 4, which is mainly used for managing DNS settings such as creating, updating and deleting DNS records.
If you encounter any bugs or find missing features, feel free to report them on the GitHub Issues page.
Disclaimer
This guide comes without any warranty. Use at your own risk. The author is not responsible for potential data loss, hardware damage or keyboard mishaps!
Get It
Java 17 or higher is required.
The project has its own maven repository. Follow the instructions on the latest package to add the repository to your project.
Changelog
See changelog
Methods Overview
The methods can be categorized as follows:
Zone: list, infoRecord: list, info, create, update, delete, batch
The API provides two styles for working with DNS records:
- Traditional API: Direct method calls with explicit parameters
- Fluent API: Chainable method calls for more readable code
The following text focuses on the basic methods. For further information, take a look at
the
Instantiation of CfDnsClient
With API Token (recommended):
CfDnsClient cfDnsClient = new CfDnsClientBuilder()
.withApiTokenAuth("your-api-token")
.build();
With Email/Key (legacy):
CfDnsClient cfDnsClient = new CfDnsClientBuilder()
.withEmailKeyAuth("email@example.com", "yourApiKey")
.build();
Further options:
CfDnsClient cfDnsClient = new CfDnsClientBuilder()
.withApiTokenAuth("your-api-token")
.withBaseUrl("https://custom-api.example.com/client/v4") // must use HTTPS
.withConnectTimeout(Duration.ofSeconds(5)) // default: 10 s
.withResponseTimeout(Duration.ofSeconds(15)) // default: 30 s
.withEmptyResultThrowsException(true) // default: false
.build();
build() throws an IllegalStateException if no authentication is configured.
The client is thread-safe and should be reused, it holds a pool of HTTP connections.
CfDnsClient implements AutoCloseable, call close() (or use try-with-resources) to release the connections:
try (CfDnsClient cfDnsClient = new CfDnsClientBuilder().withApiTokenAuth("your-api-token").build()) {
// ...
}
zoneList
Retrieve all zones within the Cloudflare account.
- Returns: A list of
ZoneEntityobjects.
List<ZoneEntity> zones = cfDnsClient.zoneList();
zones.forEach(zone -> System.out.println("Zone: " + zone.getName()));
By default, up to 1000 zones are fetched in a single request. Use a PagingRequest to control paging:
List<ZoneEntity> zones = cfDnsClient.zoneList(PagingRequest.of(1, 50)); // page 1, 50 zones per page
zoneGet
Get detailed information about a specific zone by its name.
- Parameters:
String name- The zone name (e.g., "example.com").
- Returns: A
ZoneEntityobject.
ZoneEntity zone = cfDnsClient.zoneGet("example.com");
System.out.println("Zone ID: " + zone.getId());
recordList
Retrieve records for a given zone. There are two variants:
List by subdomain (recordListBySubdomain)
Retrieve all records for a specific subdomain under a given zone, optionally filtered by record types.
- Parameters:
ZoneEntity zone- The zone object.String subdomain- The subdomain relative to the zone (e.g., "www" in "www.example.com" or "my.sub" in "my.sub.example.com"). UseCfDnsClient.APEX("@") for the zone apex.RecordType... types- Optional record types to filter by. If not specified, returns all record types.
- Returns: A list of
RecordEntityobjects.
// Get all records for a specific subdomain
List<RecordEntity> wwwRecords = cfDnsClient.recordListBySubdomain(zone, "www");
// Get only A records for a specific subdomain
List<RecordEntity> wwwARecords = cfDnsClient.recordListBySubdomain(zone, "www", RecordType.A);
// Get the records of the zone apex (e.g. "example.com")
List<RecordEntity> apexRecords = cfDnsClient.recordListBySubdomain(zone, CfDnsClient.APEX);
List by type (recordListByType)
Retrieve all records of a zone, optionally filtered by record types.
// Get only A and AAAA records of a zone
List<RecordEntity> ipZoneRecords = cfDnsClient.recordListByType(zone, RecordType.A, RecordType.AAAA);
If exactly one record type is given, the filtering is done by Cloudflare, otherwise by the client.
List all records of a zone (recordList)
// Get all records of a zone
List<RecordEntity> allZoneRecords = cfDnsClient.recordList(zone);
// Get the records of a zone page by page (page 2, 100 records per page)
List<RecordEntity> pagedRecords = cfDnsClient.recordList(zone, PagingRequest.of(2, 100));
Without a PagingRequest, all pages are fetched and the complete result is returned.
With a PagingRequest, exactly the requested page is returned.
RecordEntity#getSubdomain() returns the record name relative to its zone, e.g. my.sub for
my.sub.example.com and "@" for the zone apex. The timestamps getCreatedOn() and getModifiedOn()
are of type java.time.Instant (UTC).
Group by FQDN
The static helper CfDnsClient.groupRecordsByFqdn groups a list of records by their fully qualified domain name:
Map<String, List<RecordEntity>> byFqdn = CfDnsClient.groupRecordsByFqdn(cfDnsClient.recordList(zone));
recordCreateSubdomain / recordCreate
Create a new DNS record in a specific zone.
- Parameters:
ZoneEntity zone- The DNS zone object.String subdomain- The subdomain of the new record relative to the zone (e.g., "api" in "api.example.com").int ttl- The time-to-live in seconds of the new record.RecordType type- The record type (e.g., A, AAAA, CNAME).String content- The content of the record (e.g., the IP address of an A record).
- Returns: The created
RecordEntity.
RecordEntity created = cfDnsClient.recordCreateSubdomain(zone, "api", 60, RecordType.A, "192.168.1.1");
System.out.println("Created Record ID: " + created.getId());
Alternatively, the record can be created with its fully qualified name or from a RecordEntity:
cfDnsClient.recordCreate(zone, "api.example.com", 60, RecordType.A, "192.168.1.1");
cfDnsClient.recordCreate(zone, RecordEntity.build("api.example.com", RecordType.A, 60, "192.168.1.1"));
Records which need more than a content, like MX, SRV or CAA records, can be created from a RecordEntity.
Besides priority and data, the attributes proxied, comment and tags are supported:
// MX record with priority
RecordEntity mx = RecordEntity.build("example.com", RecordType.MX, 3600, "mail.example.com");
mx.setPriority(10);
cfDnsClient.recordCreate(zone, mx);
// SRV record with structured data (keys as in the Cloudflare API), the priority is part of the data
RecordEntity srv = RecordEntity.build("_sip._tcp.example.com", RecordType.SRV, 3600, null);
srv.setData(Map.of("priority", 10, "weight", 5, "port", 5060, "target", "sip.example.com"));
cfDnsClient.recordCreate(zone, srv);
recordUpdate
Update an existing DNS record (partial update: attributes which are null remain unchanged).
Read-only attributes like timestamps are ignored, the given RecordEntity isn't modified.
- Parameters:
ZoneEntity zone- The zone that contains the record.RecordEntity rec- Updated record data.
record.setContent("192.168.1.2");
RecordEntity updated = cfDnsClient.recordUpdate(zone, record);
System.out.println("Updated Record: " + updated.getContent());
recordDelete
Delete a DNS record from a zone.
- Parameters:
ZoneEntity zone- The parent zone.RecordEntity rec- Record to delete.
boolean isDeleted = cfDnsClient.recordDelete(zone, record);
System.out.println(isDeleted ? "Deletion successful." : "Deletion failed.");
If only the ID is known, the record can be deleted by its ID:
cfDnsClient.recordDelete(zone, record.getId());
recordDeleteTypeIfExists
Delete the DNS records of the given types if they exist.
- Parameters:
ZoneEntity zone- Target zone.String subdomain- The subdomain relative to the zone.RecordType... types- One or more record types.
cfDnsClient.recordDeleteTypeIfExists(zone, "api", RecordType.A, RecordType.AAAA);
System.out.println("Deletion attempt completed.");
Batch Operations
Process multiple DNS record operations (POST, PUT, PATCH, DELETE) in a single batch request.
- Parameters:
ZoneEntity zone- The target zone.List<RecordEntity> postRecords- Records to create (nullable). Can be built without IDs.List<RecordEntity> putRecords- Records to fully replace (nullable). Requires record IDs.List<RecordEntity> patchRecords- Records to partially update (nullable). Requires record IDs.List<RecordEntity> deleteRecords- Records to delete (nullable). Requires record IDs.
- Returns: A
BatchEntryobject containing the processed records.
Important: For UPDATE (PATCH), REPLACE (PUT), and DELETE operations, you must first retrieve the existing records to obtain their IDs.
Batch Create (POST)
Create new records, IDs are not required:
List<RecordEntity> newRecords = Arrays.asList(
RecordEntity.build("cdn." + zone.getName(), RecordType.A, 60, "192.168.1.11"),
RecordEntity.build("mail." + zone.getName(), RecordType.A, 60, "192.168.1.12")
);
BatchEntry result = cfDnsClient.recordBatch(zone, newRecords, null, null, null);
System.out.println("Created "+result.getPosts().size() +" records.");
Batch Update (PATCH)
Partially update existing records. Record IDs are required - fetch them first:
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToUpdate = new ArrayList<>();
recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "api",RecordType.A).get(0));
recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
// Step 2: Modify only the fields you want to update
recordsToUpdate.forEach(record ->record.setContent("192.168.2.10"));
// Step 3: Send batch update request
BatchEntry result = cfDnsClient.recordBatch(zone, null, null, recordsToUpdate, null);
System.out.println("Updated "+result.getPatches().size() +" records.");
Batch Replace (PUT)
Fully replace existing records. Record IDs are required - fetch them first:
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToReplace = new ArrayList<>();
recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0));
recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
// Step 2: Modify all fields as needed (full replacement)
recordsToReplace.get(0).setContent("192.168.3.10");
recordsToReplace.get(0).setTtl(120);
recordsToReplace.get(1).setContent("192.168.3.11");
recordsToReplace.get(1).setTtl(120);
// Step 3: Send batch replace request
BatchEntry result = cfDnsClient.recordBatch(zone, null, recordsToReplace, null, null);
System.out.println("Replaced "+result.getPuts().size() +" records.");
Batch Delete
Delete existing records. Record IDs are required - fetch them first:
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToDelete = new ArrayList<>();
recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0));
// Step 2: Send batch delete request
BatchEntry result = cfDnsClient.recordBatch(zone, null, null, null, recordsToDelete);
System.out.println("Deleted "+recordsToDelete.size() +" records.");
Combined Batch Operations
Combine multiple operations in a single batch request:
// Create new records (no IDs needed)
List<RecordEntity> newRecords = Arrays.asList(
RecordEntity.build("new-api." + zone.getName(), RecordType.A, 60, "192.168.1.100")
);
// Fetch existing records for update/delete (IDs required)
List<RecordEntity> recordsToUpdate = Arrays.asList(
cfDnsClient.recordListBySubdomain(zone, "existing-api", RecordType.A).get(0)
);
recordsToUpdate.get(0).setContent("192.168.1.200");
List<RecordEntity> recordsToDelete = Arrays.asList(
cfDnsClient.recordListBySubdomain(zone, "old-api", RecordType.A).get(0)
);
// Execute all operations in a single batch request
BatchEntry result = cfDnsClient.recordBatch(
zone,
newRecords, // POST - create new records
null, // PUT - not used in this example
recordsToUpdate, // PATCH - update existing records
recordsToDelete // DELETE - remove records
);
System.out.println("Batch completed:");
System.out.println(" Created: "+result.getPosts().size());
System.out.println(" Updated: "+result.getPatches().size());
System.out.println(" Deleted: "+result.getDeletes().size());
Fluent API
The fluent API provides a chainable, readable interface for DNS operations. It's an alternative to the traditional API that reduces verbosity and improves code readability.
Basic Usage
// Create a DNS record
client.zone("example.com")
.getRecord("api")
.create(RecordType.A, "192.168.1.1",60);
// Get DNS records of a subdomain
List<RecordEntity> records = client.zone("example.com")
.getRecord("www", RecordType.A)
.get();
// Get all DNS records of a zone
List<RecordEntity> zoneRecords = client.zone("example.com")
.list(RecordType.A, RecordType.AAAA);
// Update a DNS record
RecordEntity updated = client.zone("example.com")
.getRecord("api", RecordType.A)
.update("192.168.1.2");
// Delete DNS records
client.zone("example.com")
.getRecord("old-service")
.delete(RecordType.A, RecordType.AAAA);
Advantages of Fluent API
- More Readable: The chain of method calls reads like natural language
- Less Verbose: No need to pass zone objects between method calls
- Type Safe: Full compile-time type checking
- IDE Friendly: Excellent autocomplete support
Complete Example
CfDnsClient client = new CfDnsClientBuilder()
.withApiTokenAuth("your-api-token")
.build();
// Create a new record
client.zone("example.com")
.getRecord("api")
.create(RecordType.A, "192.168.100.1",60);
// Retrieve and verify
List<RecordEntity> records = client.zone("example.com")
.getRecord("api", RecordType.A)
.get();
System.out.println("IP: "+records.get(0).getContent());
// Update the record
client.zone("example.com")
.getRecord("api",RecordType.A)
.update("192.168.100.2");
// Clean up
client.zone("example.com")
.getRecord("api")
.delete(RecordType.A);
Notes on Error Handling
The CfDnsClient provides internal error-handling mechanisms through exceptions. For example:
CloudflareApiExceptionis thrown for errors during API communication or invalid responses.getStatusCode()returns the HTTP status code (orCloudflareApiException.NO_STATUS_CODEif there was no response) andgetErrors()the error codes and messages reported by Cloudflare.CloudflareNotFoundExceptionis thrown if Cloudflare responds with HTTP status 404 (e.g. deleting a non-existing record).CloudflareNotFoundExceptionis also thrown when the requested resource (single or multiple) is not found, if enabled via theemptyResultThrowsExceptionflag during initialization. Default isfalse, meaning empty results will be returned without throwing an exception.
To enable exception throwing for empty results:
CfDnsClient client = new CfDnsClientBuilder()
.withApiTokenAuth("your-api-token")
.withEmptyResultThrowsException(true)
.build();
Example:
try {
List<RecordEntity> records = cfDnsClient.recordListBySubdomain(zone, "www", RecordType.A);
System.out.println("Record IP: "+records.get(0).getContent());
} catch (CloudflareApiException e) {
if (e instanceof CloudflareNotFoundException) {
log.warn("Subdomain not found: www");
} else {
log.error("Error while getting records of subdomain www (HTTP status {}, errors {})",
e.getStatusCode(), e.getErrors(), e);
throw e;
}
}