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: .. image:: postman-1.png 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: .. image:: postman-2.png 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. .. image:: postman-3.png Obtención de lista de dominios (GET, v2.0) ++++++++++++++++++++++++++++++++++++++++++ La lista completa de dominios de un reseller se obtiene de la siguiente manera: .. image:: postman-4.png .. 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. .. code-block:: bash 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: .. image:: postman-5.png .. 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. .. image:: postman-6.png .. 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 .. image:: postman-7.png 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** .. image:: postman-8.png .. 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: .. image:: postman-9.png .. 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. .. image:: postman-10.png Obtencion de lista de Empresas (GET) ++++++++++++++++++++++++++++++++++++ .. image:: postman-11.png 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". .. image:: postman-12.png 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. .. image:: postman-13.png .. 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. .. image:: postman-14.png 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. .. image:: postman-15.png .. nota:: Se recomienda **suspender** a una empresa en caso de dar de baja, y recien transcurrido un cierto tiempo, proceder a un cleanup a traves del borrado. 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. .. image:: postman-16.png 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: .. image:: postman-16.png .. 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** .. image:: postman-17.png 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.: .. image:: postman-18.png .. image:: postman-19.png .. 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. .. image:: postman-20.png .. warning:: Una vez borrada la zona, no queda ningun rastro de la misma.