Introducción¶
General¶
La API REST permite a los clientes de VoIPstudio acceder gran parte de los recursos. Nuestra API tiene predicción de URL, orientadas a recursos y utiliza códigos de respuesta HTTP para indicar errores de API. Utilizamos funciones HTTP integradas, como la autenticación HTTP y los HTTP verbs, que son entendidos por los clientes HTTP disponibles en el mercado. Admitimos el intercambio de recursos de origen cruzado(cross-origin resource sharing), lo que le permite interactuar de forma segura con nuestra API desde una aplicación web del lado del cliente. Todas las respuestas de la API son devueltas en JSON, incluidos los errores.
Endpoints¶
La URL base para la API id:
https://l7api.com/v1.2/voipstudio/
Autenticación¶
La comunicación entre la aplicación de cliente y la API de VoIPstudio es segura gracias a HTTP basic authentication sobre SSL.
Antes de poder mandar peticiones a la API es necesario logarse con un email y una contraseña o mediante una API Key
que se utiliza para la autorización. Después de una auntenticación correcta la API devolverá un identificador de usuario único user_id
y un user_token
que deberán se utilizados para entrar.
E-mail y Contraseña¶
Solicitud de acceso usando email y contraseña:
curl -H "Content-Type: application/json" -X POST -d '{"email":"jsmith@example.com","password":"$ecretPas$$"}' https://l7api.com/v1.2/voipstudio/login
Solicitud de ejemplo:
POST /v1.2/voipstudio/login HTTP/1.1
User-Agent: curl/7.26.0
Host: l7api.com
Accept: */*
Content-Type: application/json
Content-Length: 55
Connection: close
{"email":"jsmith@example.com","password":"$ecretPas$$"}
Ejemplo de respuesta exitosa:
{
"message":"Login success",
"user_token":"8e9bc12575e639c993ba5dd8a0e7ce2250211b9a",
"user_id":123456
}
REST API Key¶
Para autenticar a un usuario con API Key
no es necesario iniciar sesión. La 'clave de API' deberá agregarse para este usuario en la sección de la pestaña Avanzado
del usuario (ver: https://voipstudio.mx/app/#manual.administrator.users.edit).
Esta API Key
se debe usar en lugar de user_token
durante el proceso de inicio de sesión.
Comunicación¶
La autenticación a la API se realiza a través de HTTP Basic Auth. Este tipo de autenticación debe ser una operación directa en el lenguaje que está usando. Se espera que las solicitudes entrantes manejadas por nuestra API tengan un encabezado especial con un valor codificado en base64 creado a partir de user_id
y user_token
devuelto por una respuesta de "inicio de sesión" exitosa, o user_id
y creado API Key
. Para obtener este valor base64
, codifique su user_id
y user_token
separados por punto y coma.
La cabecera de Authorization
se espera en el siguiente formato:
Authorization: Basic base64('user_id:user_token')
o
Authorization: Basic base64('user_id:API_Key')
Ejemplo de petición de autenticación::
curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:user_token')" https://l7api.com/v1.2/voipstudio/cdrs
o
curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:API_Key')" https://l7api.com/v1.2/voipstudio/cdrs
o simplemente:
curl -u user_id:user_token -H "Content-Type: application/json" https://l7api.com/v1.2/voipstudio/cdrs
o
curl -u user_id:API_Key -H "Content-Type: application/json" https://l7api.com/v1.2/voipstudio/cdrs
HTTP responses¶
VoIPstudio REST API usa códigos de respuesta HTTP convencionales para indicar el éxito o el fracaso de una solicitud de API. En general, los códigos en el rango 2xx indican éxito, los códigos en el rango 4xx indican un error que ha fallado dada la información proporcionada (por ejemplo, se omitió un parámetro requerido, etc.) y los códigos en el rango 5xx indican un error del servidor.
Cada respuesta exitosa, según el método HTTP, contiene las siguientes propiedades:
-
GET collection of resources:
data
- an array of resources datatotal
- total number of resources
-
GET single resource:
data
- resources datalinks
- links to related resources
Cada respuesta de error contiene las siguientes propiedades:
* `message` - mensaje de error genérico
* `errors` - array of error messages
Buscador y filtros¶
Para puntos finales de recopilación de datos, como GET https://l7api.com/v1.2/voipstudio/cdrs
el buscador se puede utilizar para devolver un número específico de registros de una página determinada en el conjunto de datos. Para aplicar el buscador, añada los siguientes parámetros a la URL ?page=N&limit=Z
donde N
es el numero de página y Z
el número de entradas a devolver(máximo 5000).
Para filtrar los datos, el parámetro filter
se puede pasar como una cadena en la query URL. El valor del parámetro filter
debe ser cadena codificada JSON en el formato que se muestra a continuación:
[
{"operator":"like","value":"United States","property":"name"},
{"operator":"eq","value":10,"property":"price"}
]
Agrupar entradas¶
El parámetro group_by
está disponible para agrupar registros por propiedad específica : `GET https://l7api.com/v1.2/voipstudio/cdrs?group_by=src
. Este parámetro se debe pasar como cadena en la query URL.