Visão geral da API
As áreas em que a API se divide, quem chama cada uma, e como obter os URLs base e a especificação OpenAPI a partir do catálogo do servidor.
A API cobre o trabalho de uma empresa de água ou de outro serviço público: clientes, propriedades e contas, contadores e leituras, facturação, pagamentos, crédito pré-pago, operações de campo e mensagens. Está dividida em áreas, cada uma com o seu caminho base, a sua forma de autenticação e o seu público. Esta página mostra como descobrir essas áreas e escolher a certa.
O que vai construir#
Um cliente que não tem URLs escritos no código: lê o catálogo do servidor, guarda o URL base de cada área e encontra a especificação OpenAPI a partir dele.
Pré-requisitos#
- Um ambiente sandbox ou o endereço de uma instalação.
curlejq, ou a CLIgotactlinstalada.- Para o passo 3, uma chave de API secreta de teste com a permissão
business:customers:read.
1. Ler o catálogo da API#
O catálogo segue o RFC 9727 e está sempre em /.well-known/api-catalog. Não precisa de autenticação.
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"
A resposta tem o tipo application/linkset+json e pode ficar em cache durante 300 segundos (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"}
]
}
Os caminhos acima são os que o servidor usa por omissão. O operador pode montar cada área noutro caminho ou retirá-la, e o catálogo reflecte sempre o que está montado. Por isso, resolva os URLs pelo title e não os escreva no código.
2. Escolher a área#
Área (title) |
Caminho por omissão | Quem chama |
|---|---|---|
business |
$BUSINESS_API |
Sistemas da empresa: ERP, contabilidade, automações e o painel da equipa. |
consumer |
$CONSUMER_API |
Aplicações e portais dos moradores, em nome do titular da conta. |
public |
$PUBLIC_API |
Páginas sem sessão: marca, definições do cliente, estimativas e pedidos de serviço. |
connector |
$CONNECTOR_API |
Conectores de pagamento e de mensagens. |
auth |
$AUTH_API |
Registo, entrada e gestão da identidade. |
private |
$PRIVATE_API |
Integrações externas: eventos e lotes de leituras de contadores, estado das integrações. |
platform |
$PLATFORM_API |
Administração da instalação pelo operador. |
Para começar a integrar os sistemas da empresa, use business com uma chave de API (veja Autenticação). Obtenha o URL base dessa área no catálogo, pelo title:
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog" | jq -r '.linkset[] | select(.title == "business") | .anchor'
3. Fazer um pedido à área escolhida#
curl -sS "$BUSINESS_API/customers?limit=1" \
-H "Authorization: Bearer $API_KEY"
Testar#
Siga o href de service-desc para obter a especificação OpenAPI em JSON, ou peça-a pela CLI, que também a encontra através do catálogo:
gotactl openapi