API overview
The areas the API is split into, who calls each one, and how to get base URLs and the OpenAPI spec from the server's catalog.
The API covers the day-to-day work of a water or utility provider: customers, properties and accounts, meters and readings, billing, payments, prepaid credit, field operations and messaging. It is split into areas, each with its own base path, its own way of authenticating and its own audience. This page shows how to discover those areas and pick the right one.
What you will build#
A client with no hardcoded URLs: it reads the server's catalog, keeps the base URL of each area, and finds the OpenAPI spec from there.
Prerequisites#
- A sandbox environment or the address of an installation.
curlandjq, or thegotactlCLI installed.- For step 3, a secret test API key with the
business:customers:readscope.
1. Read the API catalog#
The catalog follows RFC 9727 and always lives at /.well-known/api-catalog. It needs no authentication.
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"
The response is served as application/linkset+json and may be cached for 300 seconds (Cache-Control: public, max-age=300):
{
"linkset": [
{"anchor": "$AUTH_API", "title": "auth", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$PUBLIC_API", "title": "public", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$BUSINESS_API", "title": "business", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$CONSUMER_API", "title": "consumer", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$PLATFORM_API", "title": "platform", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$PRIVATE_API", "title": "private", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "$CONNECTOR_API", "title": "connector", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
{"anchor": "https://api.gota.umbeluzi.com/api/openapi.json", "title": "openapi"}
]
}
The paths above are the server's defaults. An operator can mount any area at a different path or leave it out, and the catalog always lists what is actually mounted. Resolve URLs by title instead of writing them into your code.
2. Pick the area#
Area (title) |
Default path | Who calls it |
|---|---|---|
business |
$BUSINESS_API |
The utility's own systems: ERP, accounting, automations and the staff dashboard. |
consumer |
$CONSUMER_API |
Resident apps and portals, acting for the account holder. |
public |
$PUBLIC_API |
Pages without a session: branding, client settings, estimates and service requests. |
connector |
$CONNECTOR_API |
Payment and messaging connectors. |
auth |
$AUTH_API |
Sign-up, sign-in and identity management. |
private |
$PRIVATE_API |
External integrations: meter events, reading batches, integration health. |
platform |
$PLATFORM_API |
Installation administration by the operator. |
To connect the utility's back-office systems, start with business and an API key (see Authentication). Read its base URL from the catalog by title:
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog" | jq -r '.linkset[] | select(.title == "business") | .anchor'
3. Call the area you picked#
curl -sS "$BUSINESS_API/customers?limit=1" \
-H "Authorization: Bearer $API_KEY"
Test it#
Follow the service-desc href to download the OpenAPI spec as JSON, or ask the CLI for it, which also finds it through the catalog:
gotactl openapi