Skip to content

Custom Actions ​

Some SDK controllers expose methods beyond standard CRUD. This page documents the three custom action patterns you will encounter.

Every custom action method sends the HTTP method its API operation declares (GET, POST, PATCH or DELETE) to that operation's URL. What the method returns follows from the operation's response: the returned resource, or None when the API responds with no content.

Variant create ​

Some controllers (DnsRecord, Address) require exactly one discriminating relationship to be set before calling store(). These controllers expose explicit store_with_* helpers, which are the recommended style.

python
import asyncio
from cacholong_sdk import connection, DnsRecord, ResourceTuple

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsRecord(api)
        record = ctrl.create()
        record["dns-zone"] = ResourceTuple("ZONE-UUID", "dns-zones")
        record["name"] = "www.example.com"
        record["dns-record-type"] = "A"
        record["content"] = "192.0.2.1"
        record["ttl"] = 300
        await ctrl.store_with_dns_zone(record)

asyncio.run(main())

Using auto-detecting store() ​

store() auto-detects which discriminating relationship is set and calls the correct variant internally. The result is identical to the explicit helper:

python
import asyncio
from cacholong_sdk import connection, DnsRecord, ResourceTuple

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsRecord(api)
        record = ctrl.create()
        record["dns-zone"] = ResourceTuple("ZONE-UUID", "dns-zones")
        record["name"] = "www.example.com"
        record["dns-record-type"] = "A"
        record["content"] = "192.0.2.1"
        record["ttl"] = 300
        await ctrl.store(record)  # auto-detects the dns-zone relationship

asyncio.run(main())

Validation errors ​

store() raises ValidationException if no discriminating relationship is set, or if more than one is set:

python
from cacholong_sdk import ValidationException

try:
    await ctrl.store(record)  # no dns-zone or dns-template set
except ValidationException as e:
    print(e.message)
    # "One of the following relationships is required: dns_zone, dns_template"

try:
    await ctrl.store(record)  # both dns-zone and dns-template set
except ValidationException as e:
    print(e.message)
    # "Only one of the following relationships may be set: dns_zone, dns_template"

Available helpers per variant controller:

ControllerHelpers
DnsRecordstore_with_dns_zone, store_with_dns_template
Addressstore_with_user, store_with_company

ID-based lifecycle actions ​

Some controllers expose action methods that accept only a UUID. The caller only needs the ID: the method sends the action's request for that resource directly, without fetching it first.

DnsZoneRestorePoint.rollback(resource_id) is an example. It sends POST /dns-zone-restore-points/{id}/rollback:

python
import asyncio
from cacholong_sdk import connection, DnsZoneRestorePoint

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsZoneRestorePoint(api)
        await ctrl.rollback("RESTORE-POINT-UUID")

asyncio.run(main())

Model-based lifecycle actions ​

Some actions take a payload. The caller builds a model with ctrl.create(), sets the fields the action needs, and passes it to the action method, together with the resource ID when the action belongs to one resource. The method sends the model's fields as the request body, using the HTTP method the action declares. It does not matter whether the model is new or fetched: the action decides the request, not the model.

The example below illustrates the pattern using DnsZone.import_(), which is available in the cacholong-cli internal package. The public SDK (cacholong-cloud-cli) does not currently expose model-based lifecycle actions, but the pattern is shown here so you can recognise it if you encounter it:

python
import asyncio
from cacholong_sdk import connection, DnsZone

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsZone(api)
        # Build a model holding the action's payload
        payload = ctrl.create()
        payload["csv_text"] = open("records.csv").read()  # CSV format: see the API docs
        # Sends POST /dns-zones/{id}/import/dns-records with the payload
        await ctrl.import_("ZONE-UUID", payload)

asyncio.run(main())

When you encounter a controller method that is not store, update, or destroy and that takes a model, it follows this pattern.