Wispro REST API

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í
http://doc.wispro.co/index.php?title=Wispro_REST_API#Listar_todos_los_clientes Página 1 de 14
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
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.
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
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 https://ip.del.server.wispro/api/clients
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 (https://github.com/rest-client/rest-client)
PHP
HTTPFul (http://phphttpclient.com/)
PHP REST Client (https://github.com/tcdent/php-restclient)
Python
Requests (http://docs.python-requests.org/en/master/)
REST Client (https://pypi.python.org/pypi/rest-client)
BASH / ZSH
CURL (https://curl.haxx.se/)
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 (http://doc.wispro.co/index.php?
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.
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=”https://192.168.1.1”
# 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

'.client.id'`
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"}
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 https://github.com/binarylogic/searchlogic#search-using-conditions-
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"}
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
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;
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
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
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
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 => Proc.new { |c| c.proxy_arp }
validates_presence_of :proxy_arp_lan_gateway, :if => Proc.new { |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 => Proc.new {|c| not c.netmask.nil? 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;
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
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 «http://doc.wispro.co/index.php?title=Wispro_REST_API&oldid=5144»
Wispro Index © All Rights Reserved

Wispro REST API - Wispro

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Wispro REST API - Wispro

Transféré par

Droits d'auteur :

Formats disponibles

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

Lo que enlaza aquí

4.5 Buscar clientes

Wispro REST API

Creación del Token

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

3. Guardamos el nuevo usuario.

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

Uso del Token

Donde acba205b14cf69a6e14b461d26c0ffce43d09dc782254dc9c091ef97b413710093da8eea28e880ab21b09c41ee949f03 es el API

curl -k -vvv -H "Authorization: Token

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

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

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

# luego ejecutamos curl con los parámetros necesarios

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

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

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

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

Ahora nuestro cliente ya tiene un nuevo nombre.

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

Con curls sería

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

Listar todos los clientes

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

Con curl sería

curl -X GET $host/api/clients

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

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

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

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

Con curl sería

curl -X GET $host/api/apply_changes

GET /api/clients(.:format) {:action=>"index", :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

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

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

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