Appearance
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.
Using explicit helpers (recommended)
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:
| Controller | Helpers |
|---|---|
DnsRecord | store_with_dns_zone, store_with_dns_template |
Address | store_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.