REST API ejemplos con Postman

En esta documentacion se ilustrara como usar la api con el programa Postman

Para eso se debera contar con un reseller_id y una APIKEY , ambos provistos por Planisys.

Note

En los ejemplos a continuacion, se utilizara myplan como reseller y a8dkd9Nk como AUTHORIZATION.

El prefijo a utilizar es siempre https://pdns-app.planisys.net:8443/api/v1 , y tanto reseller como AUTHORIZATION seran parte de los encabezados:

Obtención de bloques permitidos para resolvers (GET)

En el caso de resolvers, los bloques a los que permite acceder se declaran en la interfaz web. Su obtención su puede realizar mediante API:

Obtención de zonas RPZ activadas (GET, v2.0)

Para los resellers con licencia de Feed RPZ , este endpoint permite obtener las Response Policy Zones activadas.

Obtención de lista de dominios (GET, v2.0)

La lista completa de dominios de un reseller se obtiene de la siguiente manera:

Warning

Dependiendo de si se va a autenticar con HTTP_RESELLER o HTTP_COMPANY , en cada caso con su respectiva APIKEY, este endpoint devuelve la lista de dominios del Reseller o de la Empresa.

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

Warning

Este endpoint solo devuelve dominios activos , es decir dominios que no hayan sido suspendidos. La suspension de empresas y dominios se introdujo en la version 2.1

Obtención del SOA de un dominio (GET, v2.0)

Esta llamada get lleva el nombre del dominio en la URI , del cual se quiere obtener un JSON con los datos del SOA del dominio tonga-test6.com:

Note

en PDNS el refresh_ttl muchas veces se ve superpuesto por el mensaje NOTIFY , ya que PDNS genera la lista de zonas con una directiva de notificar a las IPs de los secundarios cada vez que hubo un cambio.

Warning

el serial esta por lo general en modo calendario , siendo YYYYMMDDHH (cuatro digitos para el año, dos para el mes, dos para el dia, dos para la hora o alternativamente dos digitos de 00 a 99). La interfaz PDNS permite sin embargo especificar, para cada dominio, si esta en modo calendario o en modo serial puro que es un numero creciente.

Obtener Resource Records de un dominio (GET)

Ejemplo: obtener un JSON con los Resource Records (registros), salvo el SOA que se obtiene aparte, del dominio tonga-test2.com.

Note

El valor de rr_prio es numerico, pero se devuelve en forma de string para facilitar la creacion de zonas en autoritativos. Solo es necesario en algunos registros como MX.

Note

El valor de rr_id es unico, y permite tanto modificar como borrar un registro

Borrar un Resource Record por ID (DELETE)

Se puede borrar un resource por ID

Si no existe o no es parte del dominio que estamos enviando en la URI, devuelve un error 400

Note

el SOA serial de la zona se incrementa automaticamente en 1 (uno)

Crear un Resource Record (POST)

La creacion de un RR dentro de una zona, devuelve el ID del mismo.

En este caso creamos un registro dentro de la zona tonga-test2.com

Warning

Se aplican las restricciones explicadas en el manual de PDNS para CNAMEs, tales como que no se permite la superposicion de CNAMEs con otros registros y por ende la prohibición de CNAME en el APEX de la zona, ya que ahí ya se encuentra el registro SOA.

Note

el SOA serial de la zona se incrementa automaticamente en 1 (uno)

Note

Una zona reversa solo admite registros NS y PTR, aparte del SOA que es creado junto con la zona.

Modificar un Resource Record por ID (PUT)

A partir de tener el ID de un RR , se puede modificar su TTL o su valor o tambien el tipo:

Note

Al disponer del ID, solo es necesario enviar los campos que se van a modificar. Es decir, no es necesario repetir todo de nuevo.

Note

el SOA serial de la zona se incrementa automaticamente en 1 (uno)

Obtener ACLs de un Reseller (GET)

Las ACLs o Access Control Lists permiten poner permisos de transferencia a aquellos dominios que estan permitidos de ser transferidos a otros servidores. Es decir, dominios cuyo contenido completo puede ser copiado.

Cada vez que se permite que un dominio sea transferido, se deben especificar IPv4 o IPv6 en forma individual o en bloque , o una clave criptografica TSIG que permita a quien lo posea, llevarse una copia del dominio sin importar la IP de origen.

Una ACL lleva un nombre, y es una lista de posibles bloques o ips individuales (es decir /32) IPv4 y/o IPv6 , y posiblemente una clave TSIG.

Obtencion de lista de Empresas (GET)

Obtencion de datos de una Empresa (GET)

Esta llamada GET debe tener un parametro en el JSON de entrada para obtener datos de una empresa llamada “vlans”.

El resultado, es un json con datos operativos de esa empresa en particular, como su apikey y si esta suspendida o no.

Note

Si quiere obtener un listado de empresas manejadas por el Reseller, debe utilizar la llamada al metodo companies.

Warning

Si el crm_id enviado en la URL no corresponde a ninguna Empresa, la llamada retorna un HTTP 400 junto con un JSON: {“msg”:”crmid01 does not exist”}

Modificacion de datos de una Empresa (PUT)

Se debe enviar en la URL un crm_id de empresa a modificar, y aquellos campos que se quiera modificar incluyendo el propio crm_id (solo se modifican aquellos valores que figuran en el JSON), p.ej.

Warning

En caso de modificar el valor de suspended , los cambios se haran efectivos hacia todos los dominios de la Empresa.

Note

Si un dominio se encuentra en estado suspended, significa que los servidores autoritativos del Reseller no lo van a anunciar/publicar.

Warning

En caso de cambiar el crm_id , se verificara que sea valido (alfanumerico, solo ‘-‘ y ‘_’ como caracteres especiales permitidos, y se lo pasara todo a minuscula por tratarse de una clave de búsqueda)

Warning

En caso de cambiar apikey, se removeran todos los espacios, ‘,’ y ‘;’, dado que no estan permitidos como parte de una clave API.

Creacion de una Empresa (POST)

Se debe enviar un crm_id con las restricciones definidas anteriormente, un name o nombre, y una apikey. El estado inicial de suspended es False, es decir la empresa está activa para que todos los dominios que se le asocien, estén a su vez activos por default a medida que vayan siendo creados.

El endpoint chequea que el crm_id no exista previamente, y que se le proporcionen name y apikey como parametros obligatorios.

En caso de ya existir el crm_id , la API devuelve un error 400 y un mensaje {“msg”:”Company nuevaempresa1 already exists”}

Borrado de una Empresa (DELETE)

Se debe enviar un crm_id con las restricciones definidas anteriormente, la apikey de la empresa por seguridad, para reafirmar el pedido.

El endpoint chequea que el crm_id exista, sino devuelve un error 400 con un mensaje {“msg”:”Company empresaxyz does not exist”}.

Warning

Este endpoint borra todos los dominios que pertenezcan a la empresa.

Creacion de una zona master (POST)

Para crear una zona master, se debe especificar a que empresa pertenece (crm_id), y un fqdn o Fully Qualified Domain Name (este ultimo en la URI). El nombre no necesita ser reconocido en el Internet, porque puede tratarse de una zona nueva o de una zona interna. Ademas, se deberan proveer datos para el registro SOA.

El tipo de serial SOA puede ser numeric o calendar (en este último caso es YYYYMMDDSS, siendo SS un valor de 0 a 99). En el caso de calendar , la cantidad de cambios se limita a 100 por día.

Si falta alguno de los datos, el endpoint devuelve un error 400 diciendo que falta un campo. Tambien hace chequeos de consistencia, p.ej. respecto al mname o Master DNS Name, que lo pone como registro NS automaticamente al crear la zona, y tambien crea el registro SOA con los datos proporcionados.

En caso de existir la zona dentro del Reseller, devolvera un error 400 con un mensaje de Zona duplicada.

La zona se crea con el parametro suspended en False, es decir la zona se activa inmediatamente.

Cambio de SOA o empresa de una zona (PUT)

REVISAR Este es un caso de cambio de metadatos de una zona, simplemente se debera proveer nuevos valores , ya sea para el SOA o la empresa, o inclusive cambiar el serial_type. Tambien sirve para incrementar artificalmente el SOA de una zona:

Note

Solo es necesario proveer aquellos valores que se vayan a modificar

Zona master reversa

Respecto a la creacion de zonas, valen las siguientes acotaciones:

Warning

en caso que la zona termine en in-addr.arpa o ip6.arpa , la zona sera considerada reversa en vez de directa. Esta metadata no se puede cambiar.

Note

A diferencia de la interfaz web, en donde se utiliza la notacion directa de una /24, p.ej. 123.221.24.0/24 para denotar la creacion de una zona reversa, en la API utilizamos 24.221.123.in-addr.arpa directamente como nombre de la zona. Actualmente PDNS solo soporta zonas /24 para registros PTR.

Note

Por ejemplo, una zona IPv6 0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa representa una /40 , con valores como p.ej. 2803:bc00::9A, el valor extendido es 2803:bc00:0000:0000:0000:0000:0000:009a. En caso de querer representar la zona 2803:bc00:0000::/64 , el nombre de la zona es mas largo 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

Suspensionn y Reanudacion de una zona (PUT)

REVISAR Una zona se puede reanudar y suspender sucesivamente utilizando llamadas PUT a los siguientes endpoints, p.ej.:

Note

Suspender una zona significa que no se publica en los DNSs autoritativos correspondientes al Reseller, donde se encuentra la Empresa a la cual pertenece la zona. Sin embargo, se pueden realizar modificaciones via Web o API a los registros de la zona, ya que los mismos se encuentran disponibles.

Borrado de una zona (DELETE)

Para borrar una zona, se debera simplemente utilizar el metodo DELETE , con lo cual se borraran tambien todos sus Resource Records incluyendo el SOA. La zona dejara de publicarse y sus registros no estaran mas disponibles.

Warning

Una vez borrada la zona, no queda ningun rastro de la misma.