Generalidades
Este artículo explica cómo crear una llamada para acceder a la API de DreamHost. Puedes usar la API de DreamHost de dos formas:
- Visitando la URL en tu buscador
- Escribiendo un script
Conectar con la API
Una llamada a la API se construye con varios valores. Los siguientes pasos te guían a través de la creación de una llamada a la API con estos valores.
Paso 1 — La URL de base
La URL de base es la misma para todas las llamadas de API. Esta es:
https://api.dreamhost.com
Todo lo que agregues después de esta URL crea su propia llamada API única.
Paso 2 — Generar una llave de API
Primero debes crear una llave API. Esta es una llave única asociada con tu cuenta y la información que deseas poner a disposición de cualquier llamada de API.
- Visita la página de API en tu panel.
- Esta página muestra todas las funciones de API disponibles. Solo las funciones que marques estarán disponibles para ti al usar la clave.
- Selecciona ¡Todas las funciones! en la parte superior si deseas tener todos los servicios disponibles.
- Da clic a Generate a new API Key now! al fondo para crear tu llave.
Se muestra tu nueva clave. Ahora puedes usar esta clave para conectarte con la API de DreamHost.
Para que una sub-cuenta pueda crear una clave API, se debe otorgar Privilegios de Cuenta de Facturación.
Por favor ten en cuenta que si una sub-cuenta crea una clave API, solo será visible para la sub-cuenta en la página API Key en el panel. El propietario de la cuenta principal no podrá ver la clave API de la sub-cuenta en su panel.
Después de la URL de base, agrega ?key= seguido de la llave. Asumiendo que tu Llave de API es 1A2B3C4D5E6F7G8H, la primera parte de tu llamada de API se vea así:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H
Paso 3 — Agregar el Comando
La Llave de API va seguida del comando de API específico que te gustaría correr. Cuando creaste tu clave, elegiste a qué comando(s) puedes acceder. Puedes encontrar los diferentes comandos en las distintas páginas de la API.
En este ejemplo, el comando para enumerar todos los registros DNS en la cuenta es usado.
El comando es dns-list_records.
Después de la Llave API, agrega &cmd= seguido del comando
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dns-list_records
Este simple comando es todo lo que necesitas para interactuar con la API. Si visitas la URL anterior en un navegador, verás una respuesta.
Hay comandos adicionales que puedes agregar para administrar y formatear la respuesta.
Paso 4 — Agregar valores
No todas las llamadas de API requieren valores específicos. Revisa la página API del comando que estás ejecutando para confirmar qué campos son necesarios.
Algunas llamadas a la API requieren que especifiques un valor. Por ejemplo, si deseas agregar un registro DNS a un dominio usando dns-add_record, debes especificar los siguientes valores:
- record: &record= seguido por el nombre del dominio
- type: &type= seguido por el tipo de registro de DNS
- value: &value= seguido por el valor de DNS a agregar
El siguiente ejemplo agregaría un registro TXT con el valor de test123 a example.com.
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dns-add_record&record=example.com&type=TXT&value=test123
Paso 5 — Escoger un formato (opcional)
Cuando haces una llamada a la API, la respuesta se devuelve en un formato específico. Puedes elegir en qué tipo de formato deseas que se devuelvan los datos agregando format= seguido del formato. Los formatos válidos son:
Lo siguiente devuelve la información en formato JSON:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=account-domain_usage&format=json
Paso 6 — Agregar un ID único a la llamada (opcional)
Puedes pasar un nuevo valor de ID único (longitud máxima: 64 caracteres) cuando envías una solicitud para asegurarte de no enviar accidentalmente el mismo comando dos veces. Esto es más útil al crear un script para ejecutar los comandos.
DreamHost recomienda usar UUIDs para este propósito, pero cualquier valor funcionará. El ID único que usas solo se aplica a su clave API específica, por lo que no necesitas preocuparte de que otros usuarios usen la misma identificación única.
Solo consultas exitosas "usan" un unique_id.
Para agregar un ID único, agrega &unique_id= seguido por el valor del ID. Por ejemplo, el valor del ID de 123456 es usado en el siguiente ejemplo:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dnslist_records&format=json&unique_id=123456
Paso 7 — Agrega un número de cuenta (opcional)
También puedes agregar el número de cuenta con el que deseas realizar las operaciones. Puedes especificar esto agregando &account= seguido del número de cuenta de la página Administrar Cuenta Por ejemplo:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=account-domain_usage&format=json&account=123456
La cuenta se predetermina automáticamente a la tuya o a la primera cuenta a la que tienes acceso.
Conectar usando un script
El siguiente es un script Bash simple que imprime a todos los suscriptores a una Lista de Anuncios específica.
- Esto usa el comando announcement_list-list_subscribers.
- La variable LISTNAME es la primera parte de la List Name encontrada en la página Lista de Anuncios Si la List Name fue testlist@example.com, esta variable puede ser testlist.
- El DOMAIN es la URL en que la lista aparece. If La List Name fue testlist@example.com esta variable puede ser example.com.
#!/bin/bash # variables KEY=1A2B3C4D5E6F7G8H CMD=announcement_list-list_subscribers FORMAT=json LISTNAME=testlist DOMAIN=example.com # commands LINK="https://api.dreamhost.com/?key=$KEY&cmd=$CMD&format=$FORMAT&listname=$LISTNAME&domain=$DOMAIN" RESPONSE=`wget -O- -q "$LINK" | python -m json.tool` # print results echo "$LINK" echo "$RESPONSE" if ! (echo $RESPONSE | grep -q 'success'); then exit 1 fi