Exemplos de REST API com Postman

Nesta documentação será ilustrado como utilizar a API com o programa Postman

Para isso será necessário possuir um reseller_id e uma APIKEY, ambos fornecidos pela Planisys.

Nota

Nos exemplos a seguir, será utilizado myplan como reseller e a8dkd9Nk como AUTHORIZATION.

O prefixo a ser utilizado é sempre https://pdns-app.planisys.net:8443/api/v1, e tanto reseller quanto AUTHORIZATION farão parte dos cabeçalhos:

Obtenção de blocos permitidos para resolvers (GET)

No caso dos resolvers, os blocos aos quais é permitido acesso são declarados na interface web. Sua obtenção pode ser realizada via API:

Obtenção de zonas RPZ ativadas (GET, v2.0)

Para os resellers com licença de Feed RPZ, este endpoint permite obter as Response Policy Zones ativadas.

Obtenção de lista de domínios (GET, v2.0)

A lista completa de domínios de um reseller é obtida da seguinte maneira:

Aviso

Dependendo se a autenticação será feita com HTTP_RESELLER ou HTTP_COMPANY, em cada caso com sua respectiva APIKEY, este endpoint retorna a lista de domínios do Reseller ou da Empresa.

curl -X GET ${PDNS_APIURI}/api/v1/domain_list -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"

Aviso

Este endpoint retorna apenas domínios ativos, ou seja, domínios que não tenham sido suspendidos. A suspensão de empresas e domínios foi introduzida na versão 2.1.

Obtenção do SOA de um domínio (GET, v2.0)

Esta chamada GET leva o nome do domínio na URI, do qual se deseja obter um JSON com os dados do SOA do domínio tonga-test6.com:

Nota

no PDNS, o refresh_ttl muitas vezes é sobreposto pela mensagem NOTIFY, já que o PDNS gera a lista de zonas com uma diretiva para notificar os IPs dos secundários sempre que houver uma alteração.

Aviso

o serial geralmente está em modo calendário, no formato YYYYMMDDHH (quatro dígitos para o ano, dois para o mês, dois para o dia, dois para a hora ou, alternativamente, dois dígitos de 00 a 99). A interface PDNS permite, no entanto, especificar para cada domínio se está em modo calendário ou em modo serial puro, que é um número crescente.

Modificação do SOA de um domínio (POST)

POST /api/v1/update_soa/{company_short}/{domain}/{mname}/{rname}/{serial}/{refresh}/{retry}/{expire}/{minimum}/{ttl}

Atualiza o registro SOA de uma zona DNS.

params

company_short: Identificador da empresa (crm_id)
domain: Nome do domínio
mname: Servidor DNS primário
rname: Email do responsável (formato DNS, sem @)
serial: Número de série da zona
refresh/retry/expire/minimum: Valores do SOA
ttl: TTL do registro SOA

headers

Authorization: API Key
Reseller: Identificador do reseller

Obter Resource Records de um domínio (GET)

Exemplo: obter um JSON com os Resource Records (registros), exceto o SOA, que é obtido separadamente, do domínio tonga-test2.com.

Nota

O valor de rr_prio é numérico, mas é retornado como string para facilitar a criação de zonas em autoritativos. Ele só é necessário em alguns registros, como MX.

Nota

O valor de rr_id é único e permite tanto modificar quanto remover um registro.

Remover um Resource Record por ID (DELETE)

É possível remover um resource por ID

Se ele não existir ou não fizer parte do domínio que estamos enviando na URI, retorna um erro 400

Nota

o serial SOA da zona é incrementado automaticamente em 1 (um)

Criar um Resource Record (POST)

A criação de um RR dentro de uma zona retorna o ID correspondente.

Neste caso criamos um registro dentro da zona tonga-test2.com

Aviso

Aplicam-se as restrições explicadas no manual do PDNS para CNAMEs, como a não permissão de sobreposição de CNAMEs com outros registros e, portanto, a proibição de CNAME no APEX da zona, pois ali já se encontra o registro SOA.

Nota

o serial SOA da zona é incrementado automaticamente em 1 (um)

Nota

Uma zona reversa admite apenas registros NS e PTR, além do SOA que é criado junto com a zona.

Modificar um Resource Record por ID (PUT)

A partir do ID de um RR, é possível modificar seu TTL, seu valor ou também o tipo:

Nota

Ao dispor do ID, só é necessário enviar os campos que serão modificados. Ou seja, não é necessário repetir tudo novamente.

Nota

o serial SOA da zona é incrementado automaticamente em 1 (um)

Obter ACLs de um Reseller (GET)

As ACLs ou Access Control Lists permitem definir permissões de transferência para domínios que estão autorizados a ser transferidos para outros servidores. Ou seja, domínios cujo conteúdo completo pode ser copiado.

Cada vez que se permite a transferência de um domínio, devem ser especificados IPv4 ou IPv6 de forma individual ou em bloco, ou uma chave criptográfica TSIG que permita a quem a possua obter uma cópia do domínio independentemente do IP de origem.

Uma ACL possui um nome e é uma lista de possíveis blocos ou IPs individuais (ou seja, /32) IPv4 e/ou IPv6, e possivelmente uma chave TSIG.

Obtenção de lista de Empresas (GET)

Obtenção de dados de uma Empresa (GET)

Esta chamada GET deve ter um parâmetro no JSON de entrada para obter dados de uma empresa chamada «vlans».

O resultado é um JSON com dados operacionais dessa empresa em particular, como sua apikey e se ela está suspensa ou não.

Nota

Se desejar obter uma lista de empresas gerenciadas pelo Reseller, deve utilizar a chamada ao método companies.

Aviso

Se o crm_id enviado na URL não corresponder a nenhuma Empresa, a chamada retorna um HTTP 400 junto com um JSON: {«msg»:»crmid01 does not exist»}

Modificação de dados de uma Empresa (PUT)

Deve-se enviar na URL um crm_id da empresa a ser modificada, e os campos que se deseja modificar, incluindo o próprio crm_id (somente os valores presentes no JSON serão modificados), por exemplo.

Aviso

Caso o valor de suspended seja modificado, as alterações serão efetivas para todos os domínios da Empresa.

Nota

Se um domínio estiver no estado suspended, significa que os servidores autoritativos do Reseller não irão anunciá-lo/publicá-lo.

Aviso

Caso o crm_id seja alterado, será verificado se ele é válido (alfanumérico, apenas “-“ e “_” como caracteres especiais permitidos, e será convertido para minúsculas por se tratar de uma chave de busca).

Aviso

Caso a apikey seja alterada, todos os espaços, “,” e “;” serão removidos, pois não são permitidos como parte de uma chave API.

Criação de uma Empresa (POST)

Deve-se enviar um crm_id com as restrições definidas anteriormente, um name ou nome, e uma apikey. O estado inicial de suspended é False, ou seja, a empresa está ativa para que todos os domínios associados a ela também estejam ativos por padrão à medida que forem criados.

O endpoint verifica se o crm_id não existe previamente e se foram fornecidos name e apikey como parâmetros obrigatórios.

Caso o crm_id já exista, a API retorna um erro 400 e uma mensagem {«msg»:»Company nuevaempresa1 already exists»}

Remoção de uma Empresa (DELETE)

Deve-se enviar um crm_id com as restrições definidas anteriormente e a apikey da empresa por segurança, para reafirmar a solicitação.

O endpoint verifica se o crm_id existe; caso contrário, retorna um erro 400 com a mensagem {«msg»:»Company empresaxyz does not exist»}.

Aviso

Este endpoint remove todos os domínios pertencentes à empresa.

Nota

Recomenda-se suspender uma empresa em caso de desativação e, somente após algum tempo, proceder a uma limpeza por meio da remoção.

Criação de uma zona master (POST)

Para criar uma zona master, deve-se especificar a qual empresa ela pertence (crm_id) e um fqdn ou Fully Qualified Domain Name (este último na URI). O nome não precisa ser reconhecido na Internet, pois pode se tratar de uma zona nova ou interna. Além disso, deverão ser fornecidos dados para o registro SOA.

O tipo de serial SOA pode ser numeric ou calendar (neste último caso é YYYYMMDDSS, sendo SS um valor de 0 a 99). No caso de calendar, a quantidade de alterações é limitada a 100 por dia.

Se faltar algum dos dados, o endpoint retorna um erro 400 informando que falta um campo. Também realiza verificações de consistência, por exemplo em relação ao mname ou Master DNS Name, que é colocado automaticamente como registro NS ao criar a zona, e também cria o registro SOA com os dados fornecidos.

Caso a zona já exista dentro do Reseller, retornará um erro 400 com uma mensagem de Zona duplicada.

A zona é criada com o parâmetro suspended em False, ou seja, a zona é ativada imediatamente.

Zona master reversa

Em relação à criação de zonas, valem as seguintes observações:

Aviso

caso a zona termine em in-addr.arpa ou ip6.arpa, a zona será considerada reversa em vez de direta. Esta metadata não pode ser alterada.

Nota

Diferentemente da interface web, onde se utiliza a notação direta de uma /24, por exemplo 123.221.24.0/24 para indicar a criação de uma zona reversa, na API utilizamos 24.221.123.in-addr.arpa diretamente como nome da zona. Atualmente o PDNS suporta apenas zonas /24 para registros PTR.

Nota

Por exemplo, uma zona IPv6 0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa representa uma /40, com valores como, por exemplo, 2803:bc00::9A; o valor expandido é 2803:bc00:0000:0000:0000:0000:0000:009a. Caso se deseje representar a zona 2803:bc00:0000::/64, o nome da zona é mais longo: 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa

Suspensão e Reativação de uma zona (PUT)

REVISAR Uma zona pode ser reativada e suspensa sucessivamente utilizando chamadas PUT aos seguintes endpoints, por exemplo:

Nota

Suspender uma zona significa que ela não será publicada nos DNSs autoritativos correspondentes ao Reseller onde está a Empresa à qual a zona pertence. No entanto, podem ser feitas modificações via Web ou API nos registros da zona, pois eles permanecem disponíveis.

Remoção de uma zona (DELETE)

Para remover uma zona, deve-se simplesmente utilizar o método DELETE, com o qual também serão removidos todos os seus Resource Records, incluindo o SOA. A zona deixará de ser publicada e seus registros não estarão mais disponíveis.

Aviso

Uma vez removida a zona, não resta nenhum rastro dela.