REST API – Manual

En este artículo aprenderá:

• Cómo funciona WEDOS REST API
• Cuáles son los endpoints disponibles
• Cómo gestionar los clientes API
• Cómo funciona el registro de solicitudes a la API
• Preguntas frecuentes

---

Características de WEDOS REST API

HTTP REST API v2 le permite gestionar sus servicios de WEDOS desde sus propias aplicaciones y scripts. Toda la comunicación se realiza por HTTPS en la dirección https://api.wedos.com, y los datos se envían y se devuelven en formato JSON.

Para obtener acceso a la API es necesario crear un cliente API con permisos de acceso (de lectura y escritura, o solo de lectura; consulte el capítulo Gestión de clientes ) a uno o varios endpoints (consulte Endpoints). Cada solicitud queda registrada (consulte Registro de solicitudes).

Límite de solicitudes

• El límite predeterminado es de 1.000 solicitudes por hora por cada cliente API. Cada cliente tiene su propio límite, compartido entre todas las API (domains, wdns, wgp, …).
• Todas las solicitudes cuentan para el límite, incluidas las rechazadas.
• El límite actual se muestra en la lista de clientes del panel de administración.
• Si el límite no le resulta suficiente, póngase en contacto con el soporte al cliente a través del formulario ⧉. Indique el límite deseado y el motivo por el que desea establecerlo. Podemos aumentarlo individualmente para su cuenta.

HTTP REST API vs. WAPI

WEDOS ofrece dos API: la más antigua WAPI y la más reciente HTTP REST API v2. Puede compararlas mediante la siguiente tabla:

	WAPI	HTTP REST API v2
Autenticación	Un único nombre de usuario y una contraseña WAPI para toda la cuenta	Un cliente API independiente con su propio token para cada aplicación o persona
Restricciones de acceso	Una lista obligatoria de direcciones IP para toda la cuenta	Permisos (scopes), «Solo lectura», direcciones IP y validez del token, configurados para cada cliente por separado
Formato	XML o JSON, un único endpoint, comandos en el cuerpo de la solicitud	REST (métodos HTTP y URL), JSON
Cobertura	Una amplia gama de comandos para los servicios de WEDOS	dominios, contactos, NSSETs, WEDOS DNS, WEDOS Global Protection
Log	Un único log para toda la cuenta	Un log que identifica al cliente API

Recomendamos utilizar:

• HTTP REST API v2 para nuevas integraciones cuando cubra las operaciones que necesita, y siempre que necesite separar el acceso de personas o sistemas concretos, limitarlos a solo lectura o rastrear quién hizo qué (auditoría, DORA).
• WAPI para las operaciones que HTTP REST API v2 todavía no ofrece.

Si desea pasar de WAPI a WEDOS REST API, siga estos pasos:

1. En la administración, cree para cada aplicación o sistema un cliente API con los permisos (scopes) necesarios. Encontrará las instrucciones en el capítulo Gestión de clientes .
2. Sustituya las llamadas a los comandos de WAPI por los endpoints correspondientes de la documentación de cada API. Consulte el capítulo Endpoints .
3. Los códigos de resultado de la operación (por ejemplo 1000 OK, 3201 el dominio ya está registrado) son los mismos que en WAPI, porque HTTP REST API v2 realiza las mismas operaciones. Además, existen códigos generales de la capa REST (por ejemplo 2000 token ausente o no válido, 2012 cliente de solo lectura), descritos en la documentación de cada API.
4. Durante la transición puede utilizar ambas API simultáneamente.

---

Endpoints

WEDOS REST API permite automatizar la gestión de las siguientes áreas:

• Dominios: Los endpoints /domains/ se encargan del registro, las transferencias y las renovaciones de dominios. También pueden enviar AUTH-ID y configurar servidores DNS/NSSET y KEYSET para DNSSEC. Su permiso (scope) es dominios. Encontrará más información en el artículo REST API – Dominios .
• Contactos de dominio: Los endpoints /contacts/ crean y gestionan los contactos de dominio. Las transferencias están disponibles para los dominios .cz. Su permiso (scope) es dominios. Encontrará más información en el artículo REST API – Contactos de dominio .
• NSSETs: Los endpoints /nssets/ crean y gestionan los objetos NSSET de la asociación CZ.NIC. Su permiso (scope) es dominios. Encontrará más información en el artículo REST API – NSSET de dominio .
• DNS: El endpoint /dns/ crea y gestiona dominios DNS, así como registros individuales. Esto incluye las importaciones al DNS primario y AXFR para el DNS secundario. Su permiso (scope) es dns. Encontrará más información en el artículo REST API – DNS .
• WEDOS.protection: El endpoint /wgp/ endpoints crean y gestionan los servicios WEDOS.protection. Su scope de permisos es wgp. Encontrará más información en los artículos REST API – WGP Domains, REST API – WGP Services y REST API – WGP Members.

---

Gestión de clientes

El acceso a la API se configura en la administración de clientes, en la sección HTTP REST API . Para cada aplicación, sistema o persona, cree un cliente API independiente. Para cada cliente se configura:

• Permisos (scopes): a qué API puede acceder el cliente,
• Solo lectura: el cliente solo puede consultar información (véase más abajo),
• Filtrado de direcciones IP: direcciones IP permitidas o bloqueadas desde las que el cliente puede llamar a la API,
• Validez del token: cuándo empieza a ser válido el access token y cuándo expira.

El cliente se autentica con un access token en la cabecera Authorization: Bearer <TOKEN> . Puede generar el token directamente en la administración, o su aplicación puede solicitarlo por sí misma mediante el client ID y el client secret (consulte el capítulo OAuth2 ).

Creación de un nuevo cliente

Un nuevo cliente solo se puede crear en la administración de clientes. Siga estos pasos:

1. Inicie sesión en la administración de clientes.
2. Vaya a la interfaz WEDOS REST API (actualmente no disponible).
3. Haga clic en el botón Nuevo cliente .
4. Introduzca un Nombre de cliente (un nombre corto que identifique al cliente en la lista) y elija una o varias áreas de permisos en el menú Seleccionar permisos . Las áreas disponibles corresponden a los endpoints.
5. Opcionalmente, realice otros ajustes:
   • Marque el acceso Solo lectura . El cliente podrá entonces únicamente solicitar información. Las solicitudes que añaden, actualizan o eliminan elementos quedan bloqueadas.
   • En la sección Validez del token, elija cuánto tiempo permanece válido el token tras su emisión: Sin expiración, 7 días, 30 días, 90 días, 1 año o Personalizado. Los campos Válido desde y Expiración muestran las fechas resultantes.
   • En la sección Restricciones de seguridadpuede activar opcionalmente el Filtrado de direcciones IP e introducir una dirección IP permitida. Para añadir más direcciones, haga clic en + Añadir otra , o en × para eliminar una dirección. Si el filtrado está activado, la API solo acepta solicitudes desde las direcciones indicadas.

Una vez completada la configuración, confírmela con el botón Crear cliente .

El nuevo cliente aparece en la lista con su nombre, sus permisos, el tipo de acceso (por ejemplo read, write), las fechas de validez y el estado. Puede filtrar la lista por los siguientes elementos: Permisos, Estado, Validez y Acceso.

Client Secret

Inmediatamente después de crear un cliente aparece el diálogo Clave secreta del cliente con el mensaje Copie la clave secreta y guárdela en un lugar seguro.

1. Haga clic en Copiar junto a la clave secreta.
2. Guarde la clave secreta en un lugar seguro, por ejemplo en un gestor de contraseñas o en el almacén de secretos de su servidor.
3. Haga clic en Entendido, cerrar.

La clave secreta se muestra únicamente en este diálogo, así que guárdela antes de cerrarlo. La necesita junto con el client ID para solicitar tokens a través de la API (consulte el capítulo OAuth2).

Gestión de un cliente existente

Para abrir la página Configuración de HTTP REST API de un cliente, haga clic en el icono de edición junto a su nombre en la lista. Puede modificar cualquier ajuste introducido durante la creación, incluidos el nombre y los permisos.

El Client ID y el Client Secret no se pueden modificar.

Durante la gestión de un cliente existente están disponibles los siguientes controles:

• Guardar cambios: guarda los cambios en la configuración del cliente.
• Desactivar: desactiva (bloquea) el cliente sin eliminarlo.
• Eliminar: elimina el cliente de forma permanente.
• Volver a la lista de HTTP REST API: vuelve a la lista de clientes.
• Actualizar: vuelve a cargar la página.

Bearer token del cliente

El campo Bearer token sirve para identificar al cliente al acceder a los endpoints. Muestra el access token actual del cliente. Haga clic en Copiar para copiarlo.

Para sustituir el token, haga clic en Nuevo token. El token antiguo deja de funcionar de inmediato, así que actualice todas las aplicaciones que lo utilizan.

La sección Ejemplo (curl) muestra una solicitud lista para usar con el token actual con fines de prueba.

OAuth2

Su aplicación puede solicitar su propio token en POST https://api.wedos.com/oauth2/token mediante el client ID y la clave secreta. Cualquier otro método HTTP devuelve un error.

• Client ID: En la interfaz de gestión de clientes, haga clic en Mostrar Client ID para revelar el client ID y, a continuación, haga clic en Copiar.
• Client Secret: La clave secreta solo está disponible tras la creación de la cuenta. Encontrará más información en el capítulo Client Secret .

Utilice uno de estos dos métodos:

• HTTP Basic (recomendado): la cabecera Authorization: Basic <base64(client_id:client_secret)>. curl la construye por usted con -u 'client_id:client_secret'.
• En el cuerpo de la solicitud: los parámetros client_id y client_secret.

Envíe los parámetros en el cuerpo como application/x-www-form-urlencoded, o como JSON con la cabecera Content-Type: application/json.

Parámetro	Obligatorio	Descripción
grant_type	Sí	Siempre client_credentials
scope	No	Permisos (scopes) separados por espacios entre estas opciones: domains (incluye los contactos de dominio y NSSET), wdns y wgp. Debe ser un subconjunto de los scopes del cliente. Si se omite, el token recibe todos los scopes del cliente.
client_id, client_secret	Solo sin HTTP Basic	Credenciales del cliente

Ejemplo: HTTP Basic (recomendado)

curl -X POST -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Ejemplo: Credenciales en el cuerpo de la solicitud

curl -X POST \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Ejemplo: JSON

curl -X POST -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","scope":"domains"}' \
  'https://api.wedos.com/oauth2/token'

El campo code tiene el valor 1000 cuando se emite el token, o 2000 en caso de error de autenticación del cliente o de solicitud no válida.

En caso de éxito, data contiene:

Campo	Descripción
access_token	El token, enviado como Authorization: Bearer <TOKEN>
token_type	Tipo de token (Bearer)
expires_in	Validez en segundos (3600 de forma predeterminada, es decir, 1 hora)
scope	Los scopes que el token ha recibido realmente

{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "access_token": "3f9c2e7a1b...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "domains"
  }
}

Para client_credentialsno se emite ningún refresh token. Cuando el token expire, solicite uno nuevo con la misma llamada.

En caso de error, data contiene status_code (estado HTTP de OAuth2, p. ej. 400 o 401), error y error_description.

error	Causa
invalid_client	Valor incorrecto de client_id o client_secret, o el cliente está bloqueado
invalid_request	grant_type o algún otro valor obligatorio falta, o bien el método no era POST
unsupported_grant_type	Valor no admitido del parámetro grant_type .
invalid_scope	El scope solicitado no existe o no está asignado al cliente

{
  "code": 2000,
  "msg": "API method error - Bad Request",
  "request_id": "a1b2c3d5",
  "data": {
    "status_code": 400,
    "error": "invalid_client",
    "error_description": "The client credentials are invalid"
  }
}

Envíe el valor de data.access_token en la cabecera Authorization al llamar a cualquier endpoint v2 que entre dentro del scope del token.

Ejemplo:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains'

Procure respetar las siguientes buenas prácticas:

• Guarde el token y reutilícelo hasta que expire su validez (expires_in). No solicite un nuevo token antes de cada llamada a la API.
• Si un endpoint v2 devuelve un error de autenticación (2000), solicite un nuevo token y repita la llamada.
• Solicite únicamente los scopes que su aplicación necesita y utilice Solo lectura en los clientes que nunca modifican datos.
• Siempre que sea posible, restrinja cada cliente a direcciones IP conocidas.
• Cree un cliente independiente para cada aplicación, de modo que pueda desactivar o eliminar uno sin afectar a los demás.

Configuración recomendada para equipos

Si varias personas tienen acceso a la API, recomendamos la siguiente configuración:

• Un cliente API por persona o sistema. El log muestra quién realizó cada solicitud y, cuando alguien se marcha, basta con bloquear su cliente.
• Solo los scopes necesarios. Un cliente para DNS no necesita acceso a los dominios.
• «Solo lectura» siempre que sea suficiente – supervisión, informes, comprobaciones de estado.
• Restricción a las direcciones IP de los servidores o las redes que realmente llaman a la API.
• Expiración del token. Establezca un periodo de validez y renueve el token con regularidad.
• Mantenga la clave secreta del cliente únicamente en el lado del servidor – nunca en un navegador, una aplicación móvil ni un repositorio público.

Cuando alguien se marcha:

1. Bloquee o elimine su cliente API en la lista de clientes. Todos sus tokens dejan de funcionar de inmediato y no se puede solicitar ningún token nuevo para él. Los demás clientes no se ven afectados.
2. Si otra persona asume su trabajo, cree siempre un nuevo cliente para esa persona.

---

Registro de solicitudes

La sección HTTP REST API de la administración contiene un log de solicitudes. Puede filtrarlo por permiso (scope), cliente API, estado y método HTTP.

Para acceder al log, siga estos pasos:

1. Inicie sesión en la administración de clientes.
2. Vaya a la interfaz WEDOS REST API (actualmente no disponible).
3. Haga clic en el botón Ver el log de solicitudes de HTTP REST API .

Cada cliente de la lista dispone además del enlace log , que abre el log filtrado por las solicitudes de ese cliente.

De cada solicitud registramos:

• la fecha y la hora y la dirección IP desde la que llegó la solicitud,
• el cliente API (ID y nombre) y el permiso (scope),
• el método HTTP, la URL y el comando ejecutado,
• los datos de entrada y la respuesta de la API (resultado y código de retorno).

No registramos:

• el access token ni la clave secreta del cliente: la cabecera Authorization no se almacena en el log de solicitudes y el token aparece enmascarado en los registros internos de WEDOS,
• los valores sensibles de los datos de entrada (contraseñas y similares) se almacenan enmascarados.

Otra información importante:

• Los datos de entrada y la respuesta se almacenan conjuntamente hasta 1.024 caracteres. Todo lo que supere esa longitud se trunca.
• Los registros se conservan durante 90 días, tras lo cual se eliminan automáticamente.
• Por ahora, el log no se puede exportar ni leer a través de la API. Solo está disponible en la administración de clientes.

---

Preguntas frecuentes