Wispro REST API - Wispro 21/3/18 09)49

Main Page
Go Buscar

Personal
español
Acceder
Page
Página
Discusión
Ver código
Historial

Tools
Información de la página
Enlace permanente
Versión para imprimir

Páginas especiales
Cambios relacionados

Lo que enlaza aquí

[Link] Página 1 de 14
Wispro REST API - Wispro 21/3/18 09)49

Página principal
Cambios recientes
Página aleatoria
Ayuda

Wispro REST API

Contenido
1 Wispro REST API
2 Creación del Token
3 Uso del Token
4 Uso de la API
4.1 Crear un cliente
4.2 Editar un cliente
4.3 Mostrar un cliente
4.4 Listar todos los clientes

[Link] Página 2 de 14
Wispro REST API - Wispro 21/3/18 09)49

4.5 Buscar clientes

4.6 Eliminar un cliente
4.7 Aplicar Cambios
5 Appendix
5.1 REST Clientes
5.1.1 mysql> describe clients;
5.1.2 Validations
5.2 REST Contratos
5.2.1 mysql> describe contracts;
5.2.2 Validations
5.3 REST Planes
5.3.1 mysql> describe plans;
5.3.2 Validations

Wispro REST API

Wispro cuenta con una API RESTful accesible exclusivamente via HTTPS (puerto 443).

Esta API permite hacer operaciones CRUD sobre los modelos clientes, contratos y planes. También permite hacer búsquedas filtrando
por distintos atributos.

Para poder acceder a la API hay que crear un usuario en el servidor Wispro con la opción de API habilitada y generarle una clave o
token de acceso.

Una vez teniendo el API Token, se puede acceder a los recursos expuestos por la API.

Creación del Token

Para crear el Token hay que ir al menú de usuarios en el servidor Wispro.

Allí recomendamos crear un nuevo usuario para usarlo exclusivamente con la API. Todas las operaciones que este usuario realice en el
sistema dejarán su registro en las auditoarías del sistema.

Completamos los campos requeridos como nombre, e-mail, contraseña, y luego habilitamos el acceso API con 3 simples pasos

1. Tildamos la opción de “Habilitar acceso via API para este usuario”

2. Hacemos click en “Generar nuevo API token”, debemos ver que el campo parpadea en verde y un nuevo token es mostrado en el
campo correspondiente.

3. Guardamos el nuevo usuario.

Estos 3 pasos están ilustrados en la figura que se adjunta a continuación.

[Link] Página 3 de 14
Wispro REST API - Wispro 21/3/18 09)49

El token puede regenerarse en cualquier momento, pero se debe recordar de actualizarlo también en la aplicación cliente. Es decir el
token es como una constraseña que no debe ser entregada a terceros y solo debe ser con el cliente API.

Uso del Token

Para usar el token es necesario un encabezado (header) HTTP en cada request.

El formato es el siguiente:

Authorization: Token
token=acba205b14cf69a6e14b461d26c0ffce43d09dc782254dc9c091ef97b413710093da8eea28e880ab21b09c41ee949f03

[Link] Página 4 de 14
Wispro REST API - Wispro 21/3/18 09)49

Donde acba205b14cf69a6e14b461d26c0ffce43d09dc782254dc9c091ef97b413710093da8eea28e880ab21b09c41ee949f03 es el API

token provisto en el paso anterior.

Cada request hecha con el token será autenticada con el usuario correspondiente, dando así acceso a los recursos.

Se puede probar el acceso con token via curl, por ejemplo para obtener el listado de clientes::

curl -k -vvv -H "Authorization: Token

token=acba205b14cf69a6e14b461d26c0ffce43d09dc782254dc9c091ef97b413710093da8eea28e880ab21b09c41ee949f03" -H
'Content-Type: application/json' -X GET [Link]

Uso de la API
Para usar la API basta con hacer consultas usando un cliente HTTP. La elección del cliente va a depender de que lenguaje de
programación estemos utilizando en la aplicación que va a interactuar con Wispro y de las necesidades particulares del proyecto. A
continuación ponemos algunos ejemplos de lenguajes y librerías que se pueden usar como clientes REST HTTP para acceder a la API:

Ruby
RestClient ([Link]
PHP
HTTPFul ([Link]
PHP REST Client ([Link]
Python
Requests ([Link]
REST Client ([Link]
BASH / ZSH
CURL ([Link]

Las consultas (requests) HTTP siguen el patrón REST y se corresponden con los verbos de HTTP de la siguiente manera.

Verbo
Acción CRUD Descripción
HTTP

Crear
POST Se usa para crear un nuevo registro, por ejemplo un nuevo cliente, contrato o plan.
(Create)

Leer Permite leer un registro o una colección. Es decir por ejemplo un contrato en particular, o
GET
(Read) listar todos los contratos disponibles..

Actualizar Se usa para actualizar un registro que ya existe, por ejemplo para actualizar un número
PUT
(Update/Replace) de telefono de un cliente o para cambiar de plan un contrato.

Eliminar
DELETE Elimina un registro.
(Delete)

Crear un cliente
Veamos un ejemplo concreto mirando la referencia de REST del modelo Clients ([Link]
title=Wispro_REST_API#REST_Clientes) de wispro.

En ella podemos ver que para crear un registro ( :action=> “create” ) debemos usar el método POST, usando la URL /api/clients.

[Link] Página 5 de 14
Wispro REST API - Wispro 21/3/18 09)49

POST /api/clients(.:format) {:action=>"create", :controller=>"api/clients"}

Ahora vamos a crear un cliente usando esta información desde un cliente HTTP de línea de comandos como es curl.

Primero vamos a configurar unas variables de entorno para que no tengamos que tipear tanto cada vez que invoquemos a curl, y luego
llamaremos a la API. Cabe mencionar que la API utiliza el formato JSON en la DATA de las request como las responses.

#en la variable auth guardamos el token de autenticación

auth="4eec14d7291beee0586a5e1c4c7467fea09b1d14d02b698407385efdad02994dbdaa632ab4c53e38b10e4fd07dbcc745"

# en la variables host guardamos la dirección IP o nombre DNS de nuestro servidor Wispro

host=”[Link]

# hacemos un alias de curl, para que cada vez que lo invoquemos tengamos seteados los HEADERS de auth y content-type
alias curl=’curl -k -H "Authorization: Token token=$auth" -H “Content-Type: application/json”’

# luego ejecutamos curl con los parámetros necesarios

curl -X POST $host/api/clients -d '{"client":{"name": "Ernesto Guevara"}}'</div>

Si ejecutamos estas líneas, entonces y obtenemos como respuesta HTTP un 200OK, entonces habremos creado un nuevo cliente con
nombre “Ernesto Guevara”. Es de notar, como el parámetro name (nombre), está anidado dentro de otro parámetro llamado client. Si por
ejemplo quisiéramos dar de alta el cliente junto con un número de teléfono, entonces la línea anterior sería

curl -X POST $host/api/clients -d '{"client":{"name": "Ernesto Guevara", “phone”: “555-5555”}}

En este caso damos de alta el cliente asignándole un nombre y un número de teléfono. Esta llamada a la API nos va a devolver en caso de
éxito el ID asignado al nuevo cliente. Este dato puede ser útil para luego hacer una modificación sobre el mismo. Para capturar ese ID
desde la línea de comandos podemos usar un progama llamado jq, que lo que hace es parsear una salida en JSON y mostrarla en forma
humana, o incluso parsearla para obtener un parámetro en particular como haremos en este caso.

client_id=`curl -X POST $host/api/clients -d '{"client":{"name": "Ernesto Guevara", “phone”: “555-5555”}}' | jq

'.[Link]'`

En este caso la variable client_id ahora contendrá el ID del cliente que acabamos de crear.

Editar un cliente
Supongamos que ahora quiero cambiar(actualizar) el nombre del cliente, de nuevo busco en la referencia REST de Clientes y encuentro

PUT /api/clients/:id(.:format) {:action=>"update", :controller=>"api/clients"}

Esto significa que para actualizar(update) un registro debo usar el verbo PUT, usando la URL /api/clients/:id, donde :id es el ID del
cliente que quiero modificar.

curl -X PUT $host/api/clients/$client_id -d '{"client":{"name": "Erenesto CHE Guevara"}}'

Ahora nuestro cliente ya tiene un nuevo nombre.

Mostrar un cliente
Para ver toda la información de un cliente en particular podemos usar el :action => “show”

GET /api/clients/:id(.:format) {:action=>"show", :controller=>"api/clients"}

[Link] Página 6 de 14
Wispro REST API - Wispro 21/3/18 09)49

Con curls sería

curl -X GET $host/api/clients/$client_id

Listar todos los clientes

Si quisiéramos listar todos los clientes en el servidor, podemos usar el :action => "index" de la API.

GET /api/clients/:id(.:format) {:action=>"index", :controller=>"api/clients"}

Con curl sería

curl -X GET $host/api/clients

En este caso se puede también usar el pipe a jq para tener una salida más bonita (curl ... | jq -)

Buscar clientes
El action index, además de listar todos los clientes, permite buscar usando un parámetro especial llamado search.

Por ejemplo si quiero buscar todos los clientes que se llamen ernesto, puedo usar la API de la siguiente manera

curl -X GET $host/api/clients -d '{"search":{"name_like": "ernesto"}}’

Se pueden buscar coincidencias dentro de todos los campos del modelo usando distintos parámetros dinámicos, en este caso por ejemplo
usamos el campo name, y le agregamos la palabra _like, que termina usando el LIKE de SQL. Se pueden usar otros modificadores como
_equal, _greather_than y muchos más.

Para una referencia más completa de cómo usar la búsqueda ver [Link]
on-columns

Eliminar un cliente
Por último, si queremos borrar un registro tenemos que usar el :action => “destroy”

DELETE /api/clients/:id(.:format) {:action=>"destroy", :controller=>"api/clients"}

Con curl

curl -X DELETE $host/api/clients/$client_id

Aplicar Cambios
La API también permite aplicar cambios, de la misma forma que se aplican cambios usando el botón homónimo en la interfaz web de
Wispro.

GET api_apply_changes /api/apply_changes {:controller=>"api/apply_changes", :action=>"apply_changes"}

[Link] Página 7 de 14
Wispro REST API - Wispro 21/3/18 09)49

Cuando la API devuelve 200 OK significa que se activa el proceso de aplicar cambios, el cual puede tardar unos segundos a unos minutos
en ejecutarse dependiendo de la cantidad de clientes y contratos presentes en el servidor de destino.

Con curl sería

curl -X GET $host/api/apply_changes

Appendix
REST Clientes

GET /api/clients(.:format) {:action=>"index", :controller=>"api/clients"}

POST /api/clients(.:format) {:action=>"create", :controller=>"api/clients"}
GET /api/clients/new(.:format) {:action=>"new", :controller=>"api/clients"}
GET /api/clients/:id/edit(.:format) {:action=>"edit", :controller=>"api/clients"}
GET /api/clients/:id(.:format) {:action=>"show", :controller=>"api/clients"}
PUT /api/clients/:id(.:format) {:action=>"update", :controller=>"api/clients"}
DELETE /api/clients/:id(.:format) {:action=>"destroy", :controller=>"api/clients"}

mysql> describe clients;

Field Type Null Key Default Extra

id int (11) NO PRI NULL auto_increment

name varchar (255) YES MUL NULL

email varchar (255) YES NULL

phone varchar (255) YES NULL

phone_mobile varchar (255) YES NULL

address varchar (255) YES

details text YES NULL

created_at datetime YES NULL

updated_at datetime YES NULL

external_client_number varchar (255) YES NULL

digest varchar (255) YES NULL

tmp_email varchar (255) YES NULL

[Link] Página 8 de 14
Wispro REST API - Wispro 21/3/18 09)49

taxpayer_identification_number varchar (255) YES

national_identification_number varchar (255) YES NULL

invoicing_bank_name varchar (255) YES NULL

invoicing_bank_account varchar (255) YES NULL

invoicing_bar_code_file_name varchar (255) YES NULL

invoicing_bar_code_content_type varchar (255) YES NULL

invoicing_bar_code_file_size int (11) YES NULL

invoicing_bar_code_updated_at datetime YES NULL

Validations
validates_presence_of :name

validates_length_of :name, :in => 3..128

validates_format_of :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, :allow_blank => true

REST Contratos
GET /api/contracts(.:format) {:action=>"index", :controller=>"api/contracts"}
POST /api/contracts(.:format) {:action=>"create", :controller=>"api/contracts"}
GET /api/contracts/new(.:format) {:action=>"new", :controller=>"api/contracts"}
GET /api/contracts/:id/edit(.:format) {:action=>"edit", :controller=>"api/contracts"}
GET /api/contracts/:id(.:format) {:action=>"show", :controller=>"api/contracts"}
PUT /api/contracts/:id(.:format) {:action=>"update", :controller=>"api/contracts"}
DELETE /api/contracts/:id(.:format) {:action=>"destroy", :controller=>"api/contracts"}

mysql> describe contracts;

Field Type Null Key Default Extra

id int (11) NO PRI NULL auto_increment

plan_id int (11) YES MUL NULL

client_id int (11) YES MUL NULL

date_start date YES NULL

ip varchar (255) YES UNI NULL

[Link] Página 9 de 14
Wispro REST API - Wispro 21/3/18 09)49

mac_address varchar (255) YES NULL

ceil_dfl_percent int (11) YES NULL

tcp_prio_ports varchar (255) YES NULL

udp_prio_ports varchar (255) YES NULL

prio_protos varchar (255) YES NULL

prio_helpers varchar (255) YES NULL

state varchar (255) YES NULL

created_at datetime YES NULL

updated_at datetime YES NULL

queue_down_prio float YES 0

queue_up_prio float YES 0

queue_down_dfl float YES 0

queue_up_dfl float YES 0

consumption_down_prio bigint(20) unsigned YES 0

consumption_up_prio bigint(20) unsigned YES 0

consumption_down_dfl bigint(20) unsigned YES 0

consumption_up_dfl bigint(20) unsigned YES 0

transparent_proxy varchar (255) YES default

proxy_arp tinyint (1) YES NULL

public_address_id int (11) YES NULL

proxy_arp_interface_id int (11) YES NULL

netmask varchar (255) YES NULL

cablemodem_ip varchar (255) YES NULL

cablemodem_mac_address varchar (255) YES NULL

detail varchar (255) YES NULL

cpe varchar (255) YES NULL

node varchar (255) YES NULL

unique_provider_id int (11) YES NULL

[Link] Página 10 de 14
Wispro REST API - Wispro 21/3/18 09)49

acl_behaviour varchar (255) YES NULL

pppoe_active tinyint (1) YES NULL

pppoe_username varchar (255) YES NULL

pppoe_password varchar (255) YES NULL

proxy_arp_provider_id int (11) YES NULL

proxy_arp_gateway varchar (255) YES NULL

proxy_arp_use_lan_gateway tinyint (1) YES 0

proxy_arp_lan_gateway varchar (255) YES NULL

dhcp_active tinyint (1) YES NULL

dhcp_mac_address varchar (255) YES NULL

dhcp_use_mac_control tinyint (1) YES NULL

automatic_state tinyint (1) NO 0

start_invoicing_date date YES NULL

invoicing_enabled tinyint (1) YES 0

invoicing_frecuency int (11) YES 1

charge_in_advance tinyint (1) NO 0

auto_invoice_generation tinyint (1) YES 0

auto_invoice_issuing tinyint (1) YES 0

kind_invoice_id int (11) YES MUL NULL

corporate_name varchar (255) YES

address varchar (255) YES

taxpayer_identification_number varchar (255) YES

use_information_contract_for_invoice tinyint (1) YES 0

start_date date YES NULL

send_invoicing_email_when_issue_invoices tinyint (1) YES 0

electronic_invoicing_enabled tinyint (1) YES 0

automatic_payment_enabled tinyint (1) YES NULL

[Link] Página 11 de 14
Wispro REST API - Wispro 21/3/18 09)49

invoicing_bank_name varchar (255) YES NULL

invoicing_bank_account varchar (255) YES NULL

is_connected tinyint (1) YES 0

einvoicing_vat_condition varchar (255) YES NULL

invoicing_generate_reconnection_charge tinyint (1) YES 0

traffic_accounting_bandwidth_rate_downgrade tinyint (1) YES 0

not_invoice_when_is_disabled tinyint (1) YES 0

transaction_kind_id int (11) YES NULL

time_modifiers_bandwidth_rate_downgrade int (11) YES NULL

Validations
validates_presence_of :ip, :ceil_dfl_percent, :client, :plan
validates_presence_of :proxy_arp_interface, :if => [Link] { |c| c.proxy_arp }
validates_presence_of :proxy_arp_lan_gateway, :if => [Link] { |c| c.proxy_arp_use_lan_gateway }
validates_format_of :tcp_prio_ports, :udp_prio_ports, :prio_protos, :prio_helpers, :with => /^([0-9a-z-]+(:[0-9]+)*,)*[0-9a-z-]+(:[0-
9]+)*$/, :allow_blank => true
validates_format_of :mac_address, :with => /^([0-9A-Fa-f]{2}\:){5}[0-9A-Fa-f]{2}$/, :allow_blank => true
validates_numericality_of :ceil_dfl_percent, :only_integer => true, :greater_than => 0, :less_than_or_equal_to => 100
validates_uniqueness_of :ip, :allow_nil => true, :allow_blank => true
validates_uniqueness_of :mac_address, :allow_nil => true, :allow_blank => true
validate :state_should_be_included_in_the_list
validate :uniqueness_mac_address_in_interfaces_lan
validate :ip_without_netmask, :if => "ip_changed?"
validate :check_invalid_options, :if => [Link] {|c| not [Link]? and not c.ip_is_single_host? }
validate_ip_format_of :ip, :with_netmask => true
validate_ip_format_of :proxy_arp_gateway, :with_netmask => false
validate_ip_format_of :proxy_arp_lan_gateway, :with_netmask => false

REST Planes
GET /api/plans(.:format) {:action=>"index", :controller=>"api/plans"}
POST /api/plans(.:format) {:action=>"create", :controller=>"api/plans"}
GET /api/plans/new(.:format) {:action=>"new", :controller=>"api/plans"}
GET /api/plans/:id/edit(.:format) {:action=>"edit", :controller=>"api/plans"}
GET /api/plans/:id(.:format) {:action=>"show", :controller=>"api/plans"}
PUT /api/plans/:id(.:format) {:action=>"update", :controller=>"api/plans"}
DELETE /api/plans/:id(.:format) {:action=>"destroy", :controller=>"api/plans"}

mysql> describe plans;

Field Type Null Key Default Extra

[Link] Página 12 de 14
Wispro REST API - Wispro 21/3/18 09)49

id int (11) NO PRI NULL auto_increment

name varchar (255) YES NULL

provider_group_id int (11) YES NULL

ceil_down int (11) YES NULL

ceil_up int (11) YES NULL

created_at datatime YES NULL

updated_at datatime YES NULL

transparent_proxy tinyint (1) YES 0

long_download_max int (11) YES 0

long_upload_max int (11) YES 0

long_upload_max int (11) YES 0

price_cents int (11) NO 0

price_currency varchar (255) YES NULL

due_one_days int (11) YES 10

due_two_days int (11) YES 20

due_one_interest decimal (5,2) YES 0.00

due_two_interest decimal (5,2) YES 0.00

reconnection_fee_cents int (11) NO 0

reconnection_fee_currency varchar (255) YES NULL

invoicing_enabled tinyint (1) NO 0

tax_one_id int (11) YES MUL NULL

tax_two_id int (11) YES MUL NULL

traffic_accounting_enabled tinyint (1) YES 0

decimal (20,
traffic_accounting_data YES 0
0)

invoicing_reconnection_charge_cents int (11) YES NULL

invoicing_reconnection_charge_currency varchar (255) YES NULL

traffic_accounting_bandwidth_rate float YES NULL

[Link] Página 13 de 14
Wispro REST API - Wispro 21/3/18 09)49

second_due_date_at_end_of_period tinyint (1) YES 0

cir_strategy varchar (255) YES automatic

cir float YES NULL

total_cir_up int (11) YES NULL

total_cir_down int (11) YES NULL

Validations
validates_uniqueness_of :name
validates_presence_of :name, :provider_group, :ceil_down, :ceil_up
validates_presence_of :cir_reuse, :if => lambda { |p| p.cir_strategy == CIR_STRATEGY_REUSE }
validates_presence_of :cir, :if => lambda { |p| p.cir_strategy == CIR_STRATEGY_PERCENTAGE }
validates_presence_of :total_cir_down, :total_cir_up, :if => lambda { |p| p.cir_strategy == CIR_STRATEGY_PLAN_TOTAL }
validates_length_of :name, :in => 3..128
validates_numericality_of :ceil_down, :ceil_up, :only_integer => true, :allow_nil => true, :greater_than => 0
validates_numericality_of :long_download_max, :long_upload_max, :only_integer => true, :greater_than_or_equal_to => 0, :less_than
=> 4294967295
validates_numericality_of :cir, :greater_than => 0, :less_than_or_equal_to => 1, :allow_nil => true

Obtenido de «[Link]

Wispro Index © All Rights Reserved

[Link] Página 14 de 14