Documentació de l'API de guifi.net
Taula de continguts
Descripció general
L'API de guifi.net consisteix en un grup de mètodes per poder crear, editar o esborrar els diversos objectes que conformen la xarxa lliure, oberta i neutral.
Els diversos mètodes estan classificats en 8 grans grups de mètodes, cadascun referent a la seva àrea.
Aquests grups són:
- Auth: per autenticar-se com a usuari de guifi.net i poder utilitzar els permisos d'aquest usuari
- Zone: per poder gestionar les zones dins de guifi.net
- Node: per poder gestionar els nodes dins de guifi.net
- Device: per poder gestionar els dispositius (o trastos) dins de guifi.net
- Radio: per poder gestionar les ràdios dins de guifi.net
- Interface: per poder gestionar les interfícies de les ràdios dins de guifi.net
- Link: per poder gestionar els enllaços entre nodes dins de guifi.net
- Misc: per poder agafar informació sobre diversos tipus de dades dins de guifi.net
Tots els mètodes descrits en aquests grups tenen fins a dos subapartats, els paràmetres i el retorn.
Els paràmetres és la informació bàsica que servirà per operar amb l'aplicació de guifi.net, mentre que el retorn és la informació que ens retornarà l'aplicació un cop executada l'operació.
Els paràmetres que estiguin marcats en vermell i amb un asterisc al davant (*) són obligatoris, mentre que els altres són opcionals.
Funcionament
Crides a l'API
L'API de guifi.net funciona a través del protocol HTTP.
En concret, actualment l'API només suporta el mètode GET del protocol HTTP com a entrada de dades.
Per tant, una possible crida a l'API de guifi.net s'efectuaria mitjançant l'URL:
http://guifi.net/api?command=guifi.misc.protocol
Respostes de l'API
Les respostes de l'API de guifi.net vénen donades també pel protocol HTTP.
La resposta de l'API està al contingut de la resposta HTTP, i ve formatat. Actualment, l'únic format implementat de la resposta és mitjançant JSON.
Els camps de resposta definits per la resposta de l'API de guifi.net són els següents:
| Nom | Tipus | Descripció |
|---|---|---|
| command | string | Nom del mètode al qual s'està responent. |
| code | mixed | Codi de resposta de l'API. |
| responses | mixed | Resposta que es retorna sobre el mètode que s'utilitza. Correspon al retorn de cada mètode. |
| errors | mixed | Codi d'error en la crida a un mètode de l'API. |
Per tant, una possible resposta de l'API de guifi.net (responent a la crida anterior) seria:
{"command":"guifi.misc.protocol","code":{"code":200,"str":"Request completed successfully"},"responses":{"protocols":[{"title":"802.11a","description":"802.11a (1-54Mbps - 5Ghz)"},{"title":"802.11b","description":"802.11b (1-11Mbps - 2.4Ghz)"},{"title":"802.11g","description":"802.11g (2-54Mbps - 2.4Ghz)"},{"title":"802.11n","description":"802.11n - MIMO (1-125Mbps - 2.4\/5Ghz)"},{"title":"WiMAX","description":"802.16a - WiMAX (1-125Mbps - 2-8Ghz)"},{"title":"legacy","description":"legacy\/proprietary protocol"}]}}
Codis de resposta
Tota crida que es faci a l'API de guifi.net obté un codi de resposta, tal i com s'explica a respostes de l'API.
Aquests codi de resposta està conformat pels següents camps:
| Nom | Tipus | Descripció |
|---|---|---|
| code | integer | Identificador del codi de resposta. |
| str | string | Cadena de caràcters explicativa del codi de resposta (i unívoca al codi d'error). |
A continuació hi ha un llistat amb els possibles valors que poden tenir aquests codis.
| Codi | Cadena de caràcters explicativa |
|---|---|
| 200 | Request completed successfully |
| 201 | Request could not be completed, errors found |
Codis d'error
A l'utilitzar l'API de guifi.net és possible que hi hagi crides mal formulades, que l'API no entén, o que no es poden realitzar.
Per saber si s'està en una d'aquestes crides, l'API retorna un camp de dades especial, errors, tal com s'explica a respostes de l'API.
Aquests errors està conformat pels següents camps:
| Nom | Tipus | Descripció |
|---|---|---|
| code | integer | Identificador del codi d'error. |
| str | string | Cadena de caràcters explicativa del codi d'error (i unívoca al codi d'error). |
| extra | string | Cadena de caràcters opcional, per definir més concretament l'error. Un mateix codi d'error pot venir amb diferents valors al camp extra. |
A continuació hi ha un llistat amb els possibles valors que poden tenir aquests errors.
| Codi | Cadena de caràcters explicativa |
|---|---|
| 400 | Request is not well-formatted: input command is empty or invalid |
| 401 | Request is not valid: input command is not implemented |
| 402 | Request is not valid: some mandatory fields are missing |
| 403 | Request is not valid: some input data is incorrect |
| 404 | Request is not valid: operation is not allowed |
| 500 | Request could not be completed. The object was not found |
| 501 | You don't have the required permissions |
| 502 | The given Auth token is invalid |
Mètodes
A continuació hi ha detallats els diferents grups de mètodes existents a l'API de guifi.net.
guifi.auth
Aquest grup de mètodes serveix per controlar l'autenticació contra guifi.net, i així poder gestionar correctament els permisos a utilitzar per altres mètodes.
Totes les crides a l'API de guifi.net han de començar amb un d'aquests mètodes, que permetran després executar els altres mètodes correctament.
guifi.auth.login
Autentica un usuari contra guifi.net.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| username | string | Nom d'usuari que es vol autenticar. | |
| password | string | Contrasenya de l'usuari que es vol autenticar. |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| authToken | string | Testimoni d'autenticació a utilitzar per futures consultes dins de la mateixa sessió |
guifi.zone
Aquest grup de mètodes serveix per controlar les zones dins de guifi.net.
guifi.zone.add
Afegeix una nova zona a la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| title | string | Nom de la zona a crear. | |
| nick | string | Abreviació de la zona a crear. | generat automàticament |
| zone_mode | string | Mode de la zona. Possibles valors: infrastructure (Infraestructura) i ad-hoc (Ad-hoc). | infrastructure |
| body | string | Text explicatiu per mostrar a la zona. | generat automàticament |
| master | integer | ID de la zona pare de la nova zona a crear. | |
| time_zone | integer | Fus horari de la zona a crear. | +01 2 2 |
| graph_server | string | ID del servidor de gràfiques que recull les dades de disponibilitat de la zona. | Agafat de la zona pare |
| proxy_server | string | ID del servidor proxy per defecte de la zona. | Agafat de la zona pare |
| dns_servers | string | Adreces IP dels servidors DNS de la zona, separats per comes (,). | agafat de la zona pare |
| ntp_servers | string | Adreces IP dels servidors de temps (NTP) de la zona, separats per comes (,). | agafat de la zona pare |
| ospf_zone | string | Identificador de zona OSPF de la zona a crear. | |
| homepage | string | Adreça web relacionada amb la zona a crear. | |
| notification | string | Adreça electrònica de notificació de canvis de la zona. | Adreça electrònica de l'usuari autenticat. |
| minx | float | Coordenada de longitud, en graus decimals, del límit inferior esquerre (SO) de la zona. | |
| miny | float | Coordenada de latitud, en graus decimals, del límit inferior esquerre (SO) de la zona. | |
| maxx | float | Coordenada de longitud, en graus decimals, del límit superior dret (NE) de la zona. | |
| maxy | float | Coordenada de latitud, en graus decimals, del límit superior dret (NE) de la zona. |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| zone_id | integer | ID de la zona afegida |
guifi.zone.update
Actualitza una zona a la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| zone_id | string | ID de la zona a editar. | |
| title | string | Nom de la zona | |
| nick | string | Abreviació de la zona. | generat automàticament |
| zone_mode | string | Mode de la zona. Possibles valors: infrastructure (Infraestructura) i ad-hoc (Ad-hoc). | infrastructure |
| body | string | Text explicatiu per mostrar a la zona. | generat automàticament |
| master | integer | ID de la zona pare de la zona a editar. | 0 |
| time_zone | integer | Fus horari de la zona. | +01 2 2 |
| graph_server | string | ID del servidor de gràfiques que recull les dades de disponibilitat de la zona. | Agafat de la zona pare |
| proxy_server | string | ID del servidor proxy per defecte de la zona. | Agafat de la zona pare |
| dns_servers | string | Adreces IP dels servidors DNS de la zona, separats per comes (,). | agafat de la zona pare |
| ntp_servers | string | Adreces IP dels servidors de temps (NTP) de la zona, separats per comes (,). | agafat de la zona pare |
| ospf_zone | string | Identificador de zona OSPF de la zona. | |
| homepage | string | Adreça web relacionada amb la zona. | |
| notification | string | Adreça electrònica de notificació de canvis de la zona. | Adreça electrònica de l'usuari autenticat. |
| minx | float | Coordenada de longitud, en graus decimals, del límit inferior esquerre (SO) de la zona. | |
| miny | float | Coordenada de latitud, en graus decimals, del límit inferior esquerre (SO) de la zona. | |
| maxx | float | Coordenada de longitud, en graus decimals, del límit superior dret (NE) de la zona. | |
| maxy | float | Coordenada de latitud, en graus decimals, del límit superior dret (NE) de la zona. |
guifi.zone.remove
Esborra una zona de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i una zona esborrada deixarà de mostrar-se a la pàgina web de guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| zone_id | integer | ID de la zona a esborrar. |
guifi.zone.nearest
Cerca la zona més propera a un punt del mapa.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| lat | float | Coordenada de longitud, en graus decimals, del punt pel qual volem esbrinar la zona més propera. | |
| lon | float | Coordenada de latitud, en graus decimals, del punt pel qual volem esbrinar la zona més propera. |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| nearest | array | Informació de la zona més propera al punt especificat. |
|
||
|
||
| candidates | array | Matriu d'informació amb totes les possibles zones que també inclouen el punt especificat. |
|
||
|
||
guifi.node
guifi.node.add
Afegeix un nou node (o localització) guifi.net a la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| title | string | Nom del lloc del node guifi.net. | |
| nick | string | Nom curt del lloc. | generat automàticament |
| body | string | Descripció del nou node guifi.net. | generat automàticament |
| zone_id | integer | ID de zona on estarà ubicat aquest nou lloc. | |
| zone_description | string | Descripció de la zona on està localitzat el nou node guifi.net. | |
| notification | string | Adreça electrònica de notificació de canvis del node. | Adreça electrònica de l'usuari autenticat. |
| lat | float | Latitud, en graus decimals, de la localització del nou node guifi.net. | |
| lon | float | Longitud, en graus decimals, de la localització del nou node guifi.net. | |
| elevation | integer | Elevació, en metres, de la localització del nou node guifi.net. | |
| stable | string | Serveix el node per expandir la xarxa? Possibles valors: Yes (Sí), No (No). | Yes |
| graph_server | integer | ID del servidor de gràfiques que recull les dades de disponibilitat del dispositiu. | Agafat de la zona pare |
| status | string | Estat del dispositiu. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | Working |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| node_id | integer | ID del nou node guifi.net afegit |
guifi.node.update
Actualitza un node (o localització) guifi.net a la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| node_id | integer | ID del node guifi.net a editar. | |
| title | string | Nom del lloc del node guifi.net. | |
| nick | string | Nom curt del lloc. | generat automàticament |
| body | string | Descripció del node guifi.net. | generat automàticament |
| zone_id | integer | ID de zona on està ubicat aquest lloc. | |
| zone_description | string | Descripció de la zona on està localitzat el nou node guifi.net. | |
| notification | string | Adreça electrònica de notificació de canvis del node. | Adreça electrònica de l'usuari autenticat. |
| lat | float | Latitud, en graus decimals, de la localització del node guifi.net. | |
| lon | float | Longitud, en graus decimals, de la localització del node guifi.net. | |
| elevation | integer | Elevació, en metres, de la localització del nou node guifi.net. | |
| stable | string | Serveix el node per expandir la xarxa? Possibles valors: Yes (Sí), No (No). | Yes |
| graph_server | integer | ID del servidor de gràfiques que recull les dades de disponibilitat del dispositiu. | Agafat de la zona pare |
| status | string | Estat del dispositiu. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | Working |
guifi.node.remove
Esborra un node (o localització) guifi.net de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i un node esborrat deixarà de mostrar-se a la pàgina web de guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| node_id | integer | ID del node a esborrar. |
guifi.device
Aquest grup de mètodes serveix per controlar els dispositius (o trastos) que hi ha dins de guifi.net.
Cada dispositiu està associat a un node, i hi ha diversos tipus de dispositius.
guifi.device.add
Afegeix un nou dispositiu a la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| node_id | integer | ID del node on el dispositiu s'afegirà. | |
| nick | string | Nom del nou dispositiu. | generat automàticament |
| type | string | Tipus del nou dispositiu. Possibles valors: radio (Trasto sense fils), server (Servidor), nat (Tallafocs, xarxa privada darrere NAT), generic (Trasto genèric), adsl (Router ADSL o trasto proveïdor d'accés a Internet), cam (Càmera en xarxa), phone (Telèfon mòbil VoIP). | |
| notification | string | Adreça electrònica de notificació de canvis del dispositiu. | Adreça electrònica de l'usuari autenticat. |
| mac | string | Adreça MAC del dispositiu nou a afegir (del tipus AA:BB:CC:DD:EE:FF). | |
| comment | string | Comentaris extra del dispositiu a afegir. | |
| status | string | Estat del dispositiu. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | Working |
| graph_server | integer | ID del servidor de gràfiques que recull les dades de disponibilitat del dispositiu. | Agafat del node pare |
A més, segons el camp type d'aquest mètode hi ha un seguit de camps extra que complementen la informació sobre el dispositiu que s'està afegint. Aquests altres camps estan separats a una segona taula, especificant sobre quin dispositiu s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| type = radio | |||
| model_id | integer | ID del model de trasto sense fils per afegir | |
| firmware | string | Firmware que utilitza el trasto sense fils per afegir | |
| type = adsl | |||
| download | integer | Ample de banda de baixada del dispositiu en bytes per segon. Per exemple per una velocitat de baixada de 10 Mbps, s'hi ha d'introduir 10000000. | 4000000 |
| upload | integer | Ample de banda de pujada del dispositiu en bytes per segon. Per exemple per una velocitat de pujada de 512 kbps, s'hi ha d'introduir 512000. | 640000 |
| mrtg_index | integer | Interfície SNMP per agafar informació sobre el tràfic d'aquest dispositiu. | 5 |
| type = generic | |||
| mrtg_index | integer | Interfície SNMP per agafar informació sobre el tràfic d'aquest dispositiu. | 5 |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| device_id | integer | ID del dispositiu afegit |
guifi.device.update
Actualitza un nou dispositiu de la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| device_id | integer | ID del dispositiu a editar. | |
| node_id | integer | Node on el dispositiu se situa. | |
| nick | string | Nom del dispositiu. | |
| notification | string | Adreça electrònica de notificació de canvis del dispositiu. | |
| mac | string | Adreça MAC del dispositiu (del tipus AA:BB:CC:DD:EE:FF). | |
| comment | string | Comentaris extra del dispositiu. | |
| status | string | Estat del dispositiu. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | |
| graph_server | integer | ID del servidor que recull les dades de disponibilitat del dispositiu. |
A més, segons el camp type d'aquest mètode hi ha un seguit de camps extra que complementen la informació sobre el dispositiu que s'està afegint. Aquests altres camps estan separats a una segona taula, especificant sobre quin dispositiu s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| type = radio | |||
| model_id | integer | ID del model de trasto sense fils per afegir | |
| firmware | string | Firmware que utilitza el trasto sense fils per afegir | |
| type = adsl | |||
| download | integer | Ample de banda de baixada del dispositiu en bytes per segon. Per exemple per una velocitat de baixada de 10 Mbps, s'hi ha d'introduir 10000000. | 4000000 |
| upload | integer | Ample de banda de pujada del dispositiu en bytes per segon. Per exemple per una velocitat de pujada de 512 kbps, s'hi ha d'introduir 512000. | 640000 |
| mrtg_index | integer | Interfície SNMP per agafar informació sobre el tràfic d'aquest dispositiu. | 5 |
| type = generic | |||
| mrtg_index | integer | Interfície SNMP per agafar informació sobre el tràfic d'aquest dispositiu. | 5 |
guifi.device.remove
Esborra un dispositiu de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i un dispositiu esborrat deixarà de mostrar-se a la pàgina web de guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| device_id | integer | ID del dispositiu a esborrar. |
guifi.radio
guifi.radio.add
Afegeix una nova ràdio a un dispositiu de la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| mode | string | Mode de funcionament de la ràdio. Possibles valors: Mode infrastructura: ap (AP o AP amb WDS), client (Client sense fils), routedclient (Client enrutat); Mode ad-hoc: ad-hoc (Ad-hoc) | |
| device_id | integer | Dispositiu on anirà situada aquesta ràdio. | |
| mac | string | Adreça MAC de la primera interfície de la ràdio. | A la primera ràdio es genera a partir de l'adreça MAC del dispositiu. Les altres són obligatòries. |
| antenna_angle | integer | Angle d'obertura de l'antena. Possibles valors: 0 (original/integrada), 6 (yagi/directiva), 60 (patch 60 graus), 90 (patch 90 graus), 120 (sector 120 graus), 360 (omnidirectiva). | Depèn del mode. ap: 120; client: 30; routedclient: 30; ad-hoc: 360 |
| antenna_gain | integer | Guany de l'antena. Possibles valors: 2 (2 dB), 8 (8 dB), 12 (12 dB), 14 (14 dB), 18 (18 dB), 21 (21 dB), 24 (24 dB), more (més de 24 dB). | 21 |
| antenna_azimuth | integer | Azimuth de l'antena d'aquesta ràdio, en graus. Rang de valors: 0 - 360. | 0 |
| antenna_mode | string | Connector de la ràdio on està connectada l'antena. El significat dels valors depèn del model de dispositiu. Possibles valors: Main (Principal, Dret, Intern), Aux (Auxiliar, Esquerra, Extern). | 0 |
A més, segons el camp mode d'aquest mètode hi ha un seguit de camps extra que complementen la informació sobre la ràdio que s'està afegint. Aquests altres camps estan separats a una segona taula, especificant sobre quin tipus de ràdio s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| mode = ap | |||
| ssid | string | SSID de la ràdio. | Generat a partir del nom del dispositiu |
| protocol | string | Protocol que utilitza aquesta ràdio. | 802.11b |
| channel | string | Canal de radiofreqüència que utilitza aquesta ràdio. Aquest valor depèn del protocol de la ràdio. | Automàtic |
| clients_accepted | string | Si la ràdio accepta clients o no. Possibles valors: Yes (Sí), No (No). | Yes |
| mode = ad-hoc | |||
| ssid | string | SSID de la ràdio. | Generat a partir del nom del dispositiu |
| protocol | string | Nom del protocol que utilitza aquesta ràdio. | 802.11b |
| channel | string | Canal de radiofreqüència que utilitza aquesta ràdio. Aquest valor depèn del protocol de la ràdio. | Automàtic |
Retorn
A l'afegir una ràdio a un dispositiu de guifi.net, automàticament es creen noves interfícies per aquesta ràdio.
El tipus i número d'interfícies dependrà del mode de funcionament de la pròpia ràdio. En qualsevol cas, aquestes interfícies afegides automàticament es poden tractar mitjançant el grup de mètodes d'interfície.
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| radiodev_counter | integer | Posició de la ràdio afegida en relació a altres ràdios del mateix dispositiu |
| interfaces | array | Interfícies afegides automàticament a aquesta ràdio. |
|
||
|
||
|
||
|
||
|
||
Exemple de retorn
Per clarificar els conceptes, a continuació hi ha un exemple típic d'un possible retorn agafat a l'atzar a l'hora d'afegir una ràdio nova.
array(
"radiodev_counter" = 0,
"interfaces" = array(
0 = array(
"interface_type" = "wds/p2p"
),
1 = array(
"interface_type" = "wLan/Lan"
"ipv4" = array(
0 = array(
"ipv4_type" = 1
"ipv4" = "10.145.9.33"
"netmask" = "255.255.255.224"
)
)
)
)
);
guifi.radio.update
Afegeix una nova ràdio a un dispositiu de la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| device_id | integer | Dispositiu on està situada aquesta ràdio. | |
| radiodev_counter | string | Posició de la ràdio per actualitzar en relació a altres ràdios del mateix dispositiu. | |
| antenna_angle | integer | Angle d'obertura de l'antena. Possibles valors: 0 (original/integrada), 6 (yagi/directiva), 60 (patch 60 graus), 90 (patch 90 graus), 120 (sector 120 graus), 360 (omnidirectiva). | |
| antenna_gain | integer | Guany de l'antena. Possibles valors: 2 (2 dB), 8 (8 dB), 12 (12 dB), 14 (14 dB), 18 (18 dB), 21 (21 dB), 24 (24 dB), more (més de 24 dB). | |
| antenna_azimuth | integer | Azimuth de l'antena d'aquesta ràdio, en graus. Rang de valors: 0 - 360. | |
| antenna_mode | string | Connector de la ràdio on està connectada l'antena. El significat dels valors depèn del model de dispositiu. Possibles valors: Main (Principal, Dret, Intern), Aux (Auxiliar, Esquerra, Extern). |
A més, segons el camp mode que tingui aquesta hi ha un seguit de camps extra que complementen la informació sobre la ràdio que s'està editant. Aquests altres camps estan separats a una segona taula, especificant sobre quin tipus de ràdio s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| mode = ap | |||
| ssid | string | SSID de la ràdio. | Generat a partir del nom del dispositiu |
| protocol | string | Protocol que utilitza aquesta ràdio. | 802.11b |
| channel | string | Canal de radiofreqüència que utilitza aquesta ràdio. Aquest valor depèn del protocol de la ràdio. | Automàtic |
| clients_accepted | string | Si la ràdio accepta clients o no. Possibles valors: Yes (Sí), No (No). | Yes |
| mode = ad-hoc | |||
| ssid | string | SSID de la ràdio. | Generat a partir del nom del dispositiu |
| protocol | string | Nom del protocol que utilitza aquesta ràdio. | 802.11b |
| channel | string | Canal de radiofreqüència que utilitza aquesta ràdio. Aquest valor depèn del protocol de la ràdio. | Automàtic |
guifi.radio.remove
Esborra un ràdio d'un dispositiu guifi.net de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i un radio esborrada deixarà de mostrar-se a la pàgina web de guifi.net.
Es perdran totes les configuracions IP i els enllaços associats a aquesta ràdio!
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| device_id | integer | ID del dispositiu on està situada la ràdio. | |
| radiodev_counter | integer | Dins el dispositiu, a quina posició està ubicada la ràdio que es vol esborrar. |
guifi.radio.nearest
Cerca les ràdios en mode ap més properes a un node del mapa.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| node_id | integer | Identificador del node al qual volem buscar les ràdios més properes per establir-hi un enllaç.. | |
| dmin | integer | Distància mínima a la qual han d'estar les ràdios retornades. | 0 |
| dmax | integer | Distància màxima a la qual ha d'estar les ràdios retornades. | 15 |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| radios | array | Matriu d'informació amb totes les possibles ràdios. Com a màxim retornarà 20 ràdios diferents. |
|
||
|
||
|
||
|
||
guifi.interface
guifi.interface.add
Afegeix una nova interfície a una ràdio de la xarxa.
L'API només suporta afegir interfícies de ràdio sense fils per poder afegir rangs d'adreces IP per clients.
En cas que la ràdio funcioni en mode client no es podran afegir més interfícies.
Queda per implementar el suport de les connexions per cable.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| device_id | integer | ID del dispositiu on es vol afegir la interfície. | |
| radiodev_counter | string | Posició de la ràdio on es vol afegir la interfície respecte altres ràdios del mateix dispositiu. |
Retorn
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| interface_id | integer | ID de la interfície afegida |
| ipv4 | array | Informació sobre la xarxa IPv4 que s'hagi afegit. |
|
||
|
||
|
||
guifi.interface.remove
Esborra una interfície de ràdio de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i una interfície esborrada deixarà de mostrar-se a la pàgina web de guifi.net.
L'API només suporta gestionar interfícies de ràdio sense fils.
No es poden esborrar interfícies del tipus wLan/Lan, així com tampoc hi pot haver cap ràdio sense interfícies. Les úniques interfícies que es poden treure són les de tipus wLan, les que afegeixen rangs d'IP per clients.
Queda per implementar el suport de les connexions per cable.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| interface_id | integer | ID de la interfície a esborrar. |
guifi.link
guifi.link.add
Afegeix un nou enllaç entre dues interfícies de la xarxa.
Aquest mètode només és vàlid entre interfícies del tipus Wan i wLan/Lan o wLan (els anomenats enllaços link2ap); o bé entre interfícies wds (els anomenats enllaços wds).
Segons les interfícies que s'introdueixin a aquest mètode, l'API detecterà automàticament quin tipus d'enllaç nou crear.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| from_device_id | integer | Identificador de dispositiu des d'on fer l'enllaç. | |
| from_radiodev_counter | integer | Posició de la ràdio dins del dispositiu cap on fer l'enllaç. | |
| to_device_id | integer | Identificador de dispositiu cap on fer l'enllaç. | |
| to_radiodev_counter | integer | Posició de la ràdio dins del dispositiu cap on fer l'enllaç. | |
| ipv4 | string | Adreça IP que ha de tenir el dispositiu de l'enllaç amb identificador from_device_id. Aquesta adreça es verificarà, i si no és correcta no s'afegirà l'enllaç. | Generat automàticament |
| status | string | Estat de l'enllaç. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | Working |
A més, segons el camp mode d'aquest mètode hi ha un seguit de camps extra que complementen la informació sobre l'enllaç que s'està afegint. Aquests altres camps estan separats a una segona taula, especificant sobre quin tipus d'enllaç s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| mode = link2ap | |||
| mode = wds | |||
| to_interface_id | integer | Identificador d'interfície cap on fer l'enllaç. | |
| routing | string | Tipus d'enrutament aplicat a aquest enllaç. Possibles valors: OSPF (OSPF), BGP (BGP), Static (estàtic). | BGP |
Retorn
A l'afegir un enllaç a un dispositiu de guifi.net, automàticament es s'afegeix la configuració IP de l'enllaç.
Els camps que retorna aquest mètode en cas d'èxit són els descrits a continuació:
| Nom | Tipus | Descripció |
|---|---|---|
| link_id | integer | Identificador del nou enllaç afegit |
| ipv4 | array | Informació sobre la xarxa IPv4 que s'hagi afegit a la interfície. |
|
||
|
||
|
||
Exemple de retorn
Per clarificar els conceptes, a continuació hi ha un exemple típic d'un possible retorn agafat a l'atzar a l'hora d'afegir una ràdio nova.
array(
"link_id" = 21947,
"ipv4" = array(
"ipv4_type" = 1
"ipv4" = "10.145.5.99"
"netmask" = "255.255.255.224"
)
);
guifi.link.update
Actualitza un nou enllaç de la xarxa.
Paràmetres
L'ordre bàsica d'ús d'aquest mètode conté els camps bàsics descrits a la taula de continuació.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| link_id | integer | ID de l'enllaç a editar. | |
| ipv4 | string | Adreça IP que ha de tenir el dispositiu de l'enllaç amb identificador from_device_id. Aquesta adreça es verificarà, i si no és correcta no s'afegirà l'enllaç. | Generat automàticament |
| status | string | Estat de l'enllaç. Possibles valors: Planned (Projectat), Reserved (Reservat), Building (En construcció), Testing (En proves), Working (Operatiu) i Dropped (Esborrat). | Working |
A més, segons el mode de l'enllaç a editar hi ha un seguit de camps extra que complementen la informació sobre l'enllaç que s'està editant. Aquests altres camps estan separats a una segona taula, especificant sobre quin tipus d'enllaç s'utilitzen.
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| mode = link2ap | |||
| mode = wds | |||
| routing | string | Tipus d'enrutament aplicat a aquest enllaç. Possibles valors: OSPF (OSPF), BGP (BGP), Static (estàtic). | BGP |
guifi.link.remove
Esborra un enllaç de la xarxa.
Vés amb compte
Aquesta acció no té marxa enrere, i un enllaç esborrat deixarà de mostrar-se a la pàgina web de guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| link_id | integer | ID de la enllaç a esborrar. |
guifi.misc
guifi.misc.model
Aquest mètode serveix per retornar els diversos tipus de models de dispositius (o trastos) suportats per guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| type | string | Tipus de models a retornar. Possibles valors: Extern, PCMCIA, PCI. | |
| fid | integer | ID del fabricant dels models a retornar. | |
| supported | string | Si el model està suportat o no. Possibles valors: Yes (se suporta el model), Deprecated (ja no se suporta el model). | Yes |
Retorna
| Nom | Tipus | Descripció |
|---|---|---|
| models | array | Tots els models que concorden amb els paràmetres passats |
|
||
|
||
|
||
|
||
|
||
Llistat
Un llistat útil de models de dispositius és el següent:
| mid | fid | model |
|---|---|---|
| 1 | 2 | WRT54Gv1-4 |
| 15 | 9 | WHR-HP-G54, WHR-G54S |
| 16 | 2 | WRT54GL |
| 17 | 2 | WRT54GSv1-2 |
| 18 | 2 | WRT54GSv4 |
| 19 | 8 | Supertrasto RB532 guifi.net |
| 20 | 8 | Supertrasto RB133C guifi.net |
| 21 | 8 | Supertrasto RB133 guifi.net |
| 22 | 8 | Supertrasto RB112 guifi.net |
| 23 | 8 | Supertrasto RB153 guifi.net |
| 24 | 8 | Supertrasto guifiBUS guifi.net |
| 25 | 10 | NanoStation2 |
| 26 | 10 | NanoStation5 |
| 27 | 8 | Supertrasto RB600 guifi.net |
| 28 | 8 | Supertrasto RB333 guifi.net |
| 29 | 8 | Supertrasto RB411 guifi.net |
| 30 | 11 | Meraki/Fonera |
| 31 | 8 | Supertrasto RB433 guifi.net |
| 32 | 10 | LiteStation2 |
| 33 | 10 | LiteStation5 |
| 34 | 10 | NanoStation Loco2 |
| 35 | 10 | NanoStation Loco5 |
| 36 | 10 | Bullet2 |
| 37 | 10 | Bullet5 |
| 38 | 10 | RouterStation |
| 39 | 12 | Avila GW2348-4 |
| 40 | 13 | Asus WL-500xx |
guifi.misc.manufacturer
Aquest mètode serveix per retornar els diversos fabricants de dispositius (o trastos) suportats per guifi.net.
Retorna
| Nom | Tipus | Descripció |
|---|---|---|
| manufacturers | array | Tots els fabricants suportats a guifi.net |
|
||
|
||
|
||
Llistat
Un llistat útil de fabricants de dispositius és el següent:
| fid | name | url |
|---|---|---|
| 1 | D-Link | http://www.dlink.com |
| 2 | Linksys | http://www.linksys.com |
| 3 | Conceptronic | http://www.conceptronic.net/ |
| 4 | US Robotics | http://www.usr.com |
| 5 | 3Com | http://www.3com.com |
| 6 | Zyxel | http://www.zyxel.com |
| 7 | Conceptronic | |
| 8 | Mikrotik | http://mikrotik.com |
| 9 | Buffalo | http://www.buffalotech.com |
| 10 | Ubiquiti | http://www.ubnt.com |
| 11 | Meraki | http://meraki.com |
| 12 | Gateworks | http://www.gateworks.com |
| 13 | Asus | http://www.asus.com |
| 14 | Pcengines | http://www.pcengines.ch |
| 99 | Other |
guifi.misc.firmware
Aquest mètode serveix per retornar els diversos tipus de firmwares de dispositius (o trastos) suportats per guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| model_id | integer | ID de model que suporta el firmware retornat. |
Retorna
| Nom | Tipus | Descripció |
|---|---|---|
| firmwares | array | Firmwares suportats de guifi.net retornats |
|
||
|
||
Llistat
Un llistat útil de firmwares de dispositius és el següent:
| Nom del firmware | Descripció del firmware |
|---|---|
| Alchemy | Alchemy from sveasoft |
| Talisman | Talisman from sveasoft |
| DD-WRT | DD-WRT from BrainSlayer |
| DD-guifi | DD-guifi from Miquel Martos |
| RouterOSv2.9 | RouterOS 2.9 from Mikrotik |
| whiterussian | OpenWRT-whiterussian |
| kamikaze | OpenWRT kamikaze |
| Freifunk-BATMAN | OpenWRT-Freifunk-v1.6.16 with B.A.T.M.A.N |
| RouterOSv3.x | RouterOS 3.x from Mikrotik |
| AirOsv221 | Ubiquti AirOs 2.2.1 |
| Freifunk-OLSR | OpenWRT-Freifunk-v1.6.16 with OLSR |
| AirOsv30 | Ubiquti AirOs 3.0 |
| RouterOSv4.x | RouterOS 4.x from Mikrotik |
guifi.misc.protocol
Aquest mètode serveix per retornar els diversos tipus de protocols de dispositius (o trastos) suportats per guifi.net.
No té paràmetres d'entrada, només de retorn.
Retorna
| Nom | Tipus | Descripció |
|---|---|---|
| protocols | array | Protocols suportats de guifi.net retornats |
|
||
|
||
Llistat
Un llistat útil de protocols és el següent:
| title | description |
|---|---|
| 802.11a | 802.11a (1-54Mbps - 5Ghz) |
| 802.11b | 802.11b (1-11Mbps - 2.4Ghz) |
| 802.11g | 802.11g (2-54Mbps - 2.4Ghz) |
| 802.11n | 802.11n - MIMO (1-125Mbps - 2.4/5Ghz) |
| WiMAX | 802.16a - WiMAX (1-125Mbps - 2-8Ghz) |
| legacy | legacy/proprietary protocol |
guifi.misc.channel
Aquest mètode serveix per retornar els diversos tipus de channels de dispositius (o trastos) suportats per guifi.net.
Paràmetres
| Nom | Tipus | Descripció | Per defecte |
|---|---|---|---|
| protocol | string | Nom del protocol que suporta els canals retornats. |
Retorna
| Nom | Tipus | Descripció |
|---|---|---|
| channels | array | Canals suportats de guifi.net retornats |
|
||
|
||
Llistat
Un llistat útil de canals és el següent, ordenats per nom de protocol:
| Nom del canal | Descripció del canal |
|---|---|
| 802.11b | |
| 802.11g | |
| 802.11n | |
| 0 | Auto 2.4GHz |
| 1 | 1.- 2412 MHz |
| 2 | 2-. 2417 MHz |
| 3 | 3.- 2422 MHz |
| 4 | 4.- 2422 MHz |
| 5 | 5.- 2432 MHz |
| 6 | 6.- 2437 MHz |
| 7 | 7.- 2442 MHz |
| 8 | 8.- 2447 MHz |
| 9 | 9.- 2452 MHz |
| 10 | 10.- 2457 MHz |
| 11 | 11.- 2462 MHz |
| 12 | 12.- 2467 MHz |
| 13 | 13.- 2472 MHz |
| 14 | 14.- 2477 MHz |
| 802.11a | |
| 5000 | Auto 5GHz |
| 5180 | 1.- 5180 MHz |
| 5200 | 2-. 5200 MHz |
| 5220 | 3.- 5220 MHz |
| 5240 | 4.- 5240 MHz |
| 5260 | 5.- 5260 MHz |
| 5280 | 6.- 5280 MHz |
| 5300 | 7.- 5300 MHz |
| 5320 | 8.- 5320 MHz |
| 5500 | 9.- 5500 MHz |
| 5520 | 10.- 5520 MHz |
| 5540 | 11.- 5540 MHz |
| 5560 | 12.- 5560 MHz |
| 5580 | 13.- 5580 MHz |
| 5600 | 14.- 5600 MHz |
| 5620 | 15.- 5620 MHz |
| 5640 | 16.- 5640 MHz |
| 5660 | 17.- 5660 MHz |
| 5680 | 18.- 5680 MHz |
| 5700 | 19.- 5700 MHz |
| WiMAX | |
| 0000 | Auto 2-8Ghz |
Autenticació
Per utilitzar l'API de guifi.net es necessita autenticar un usari vàlid registrat de la web de guifi.net.
Per autenticar l'usuari, s'ha de fer servir el mètode guifi.auth.login, descrit anteriorment.
Els mètodes tenen en compte els permisos de l'usuari autenticat, de manera que si aquest usuari no té permisos per fer una acció en concret, es retornarà un codi d'error.
Testimoni d'autenticació
Un cop feta l'autenticació, el mateix mètode guifi.auth.login retorna un testimoni d'autenticació (auth token), que es pot fer servir per autenticar-se sense haver d'enviar l'usuari i la contrasenya un altre cop.
Per poder fer servir aquest testimoni d'autenticació, cal que a cada futur mètode s'inclogui la següent capçalera HTTP fins de la consulta:
Authorization: GuifiLogin auth=<authToken>
on <authToken> és el testimoni d'autenticació retornat pel mètode guifi.auth.login.
Expiració del testimoni d'autenticació
Aquest testimoni d'autenticació té una data d'expiració, que és de 12 hores a partir del moment que va ser creada.
Quan aquest testimoni d'autenticació expiri, o bé el testimoni que s'enviï al servidor sigui invàlid, el servidor retornarà un codi d'error, que significarà que el client s'ha de tornar a autenticar mitjançant el mètode guifi.auth.login.
Llibreries
El codi font de l'API de guifi.net és lliure, i es pot trobar al Trac de guifi.net
A més a més, s'ofereixen als programadors que vulguin fer servir l'API de guifi.net un seguit de llibreries per poder-hi treballar més còmodament des de bon principi.
Els llenguatges de programació disponibles per aquestes llibreries són els següents:
T'animem a programar les teves pròpies llibreries en el llenguatge de programació que prefereixis, i a alliberar-ne el codi font perquè tothom en pugui fer ús!