La API de Preciosa¶
Atención
La API está en plena fase de diseño e implementación. Puede cambiar sin previo aviso
Breve intro a Django Rest Framework¶
La API REST de Preciosa está implementada con Django Rest Framework (DRF) Hay 3 módulos que importan
serializers.py
views.py
urls.py
El primero define los serializadores, conceptualmente análogos a un formulario, que dado un objeto (en general, una instancia de un Modelo), define las reglas de como debe mostrar los atributos en un formato de representación (como JSON) o, en sentido inverso, como debe recontruir un objecto a partir de una representación.
El segundo módulo define las «vistas», que son similares a las
de Django (aunque el objeto Response
que usa la API es ligeramente distinto). Para los casos de uso más comunes se pueden usar
Class Based View
(análogas a las CBV de Django, que saben
listar, mostrar, crear, etc. objetos/instancias de modelos)
o una abstracciín aún más general denominada ViewSet
, que puede pensarse como una factory de Class Based Views: un Viewset para un modelo,
ya sabe hacer todos los casos comunes y, como yapa, mediante un Router
, nos genera automáticamente una estructura de urls tipicas.
Por último, puede definirse una vista tipica como función, decorada con
el decorador de DRF @api_view
Las urls son iguales a las de cualquier aplicación Django, salvo
por la utilización opcional de un router
(una factory de URLs).
Preciosa utiliza una mezcla de todas las posilidades de que brinda DRF.
Por ejemplo, los endpoints para modelos simples como Cadena
(Walmart, Disco, etc), utilizan ViewSets
, algunos listados/detalles como el del modelo Producto
(que puede accederse en general o para una sucursal en particular) usa CBVs
y la vista de detalle para productos (en una sucursal) usa una vista basada implenentada como función decorada.
Advertencia
DISCLAIMER: Estamos aprendiendo a usar este framework sobre la marcha. Si tenés ideas de cómo mejorar, recomendaciones, etc. estaremos contentos de recibirlas.
Autenticación básica basada en token¶
La API de preciosa utiliza una manera muy simple y opcionalmente anónima de autenticación. El motivo de usar autenticación es para prevenir/aminorar el vandalismo y el uso desleal de los recursos.
Cada usuario está asociado a un token. Registrar un usuario para obtener un token
es muy fácil. Basta hacer un POST
al enpoint
Opcionalmente la petición puede enviar esta información
uuid
un identificador único del equipo (ejemplo, el movil)
nombre
un nombre elegido por el usuario para el equipo
plataforma
la plataforma subyacente (ejemplo: «Android»)
phonegap
si el cliente es Phonegap, la versión.
plataforma_version
la versión de la plataforma (ejemplo «2.2» para Android)
preciosa_version
la versión del cliente de preciosa.
Los parámetros no son obligatorios, pero cualquiera subconjunto que se envie
debe incluir el uuid
(sin uuid ninguna información quedará guardada)
Obtenido el token, este debe enviarse para cada subsecuente petición. Puede hacerse configurando el un header HTTP. Por ejemplo
Authorization: Token XXXXX
Donde XXXX es el token dado.
Desde jQuery, puede configurarse para todas las peticiones ajax
$.ajaxSetup({
headers: {
'Authorization': "Token XXXXX"
}
});
Alternativamente, se puede enviar un token como parámetro en el QUERY
de la URL. Por ejemplo:
api/v1/<end_point>/?token=XXXX
Si ya se cuenta con un usuario y contraseña (por ejemplo un Voluntario registrado via web) se puede obtener un token enviando parámetros usuario
y password
al recurso
Devuelve el token en formato json de igual manera que /auth/registro
¿Qué se puede hacer?¶
Como DRF ofrece una versión HTML del contenido de la API, gran parte de los recursos que la API de preciosa ofrece pueden autodescubrirse navegando desde la raiz.
Otros recursos¶
- Detalle de una sucursal
http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>
- Listado de productos con precios conocidos en una sucursal
http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>/productos
Es igual que
http://preciosdeargentina.com.ar/api/v1/productos
, pero filtra aquellos productos en los que para esa sucursal hay precios conocidos.- Detalle de producto para una sucursal en particular
http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>/productos/<pk_producto>
Este recurso devuelve un detalle exhaustivo de los precios probables y los mejores para una zona, incluyendo sucursales asociadas a esos mejores precios.
Filtros¶
El listado de productos (http://preciosdeargentina.com.ar/api/v1/productos) puede recibir los siguientes parámetros opcionales via GET
q
cadena a buscar. Usa el criterio definido en
Producto.objects.buscar
(es decir, dará los mismos resultados que el buscador de la web). Por ejemplo, puede ser un conjunto de palabras claves o un código de barras (completo o los primeros números desde la izquierda).limite
cuantos resultados mostrar para el criterio
pk
limita la busqueda a un PK de producto en particular
El listado de sucursales (http://preciosdeargentina.com.ar/api/v1/sucursales) puede recibir los siguientes parámetros via GET
q
cadena a buscar. Por ejemplo, nombre de ciudad, cadena, o calle.
lat
,lon
yradio
:una posición y el radio en kilometros que determina las zona donde se buscan sucursales. Estos parámetros son interdependientes.
- El listado de Ciudades (http://preciosdeargentina.com.ar/api/v1/ciudades)
puede recibir los siguientes parámetros via
GET
:q
cadena a buscar. Por ejemplo, nombre de ciudad o provincia.
Formatos¶
DRF sabe interpretar el content-type
preferido en el encabezado de la petición HTTP
. Alternativamente puede definirse mediante el parámetro
format
en la URL del recurso. Por ejemplo
Forzará el serializado de la lista de cadenas en formato JSON, aun desde un navegador web que acepta HTML.
Tasas de limitación (throttling)¶
Complementario a la autenticación, la API tiene un sistema de limitación de peticiones (throttling), para evitar el abuso de usuarios malintencionados.
Actualmente las tasas son:
30 peticiones por dia para usuarios anónimos. Actualmente permite acceder a la URL
/auth/registro
40 peticiones por minuto para usuarios autorizados. Es para evitar los picos de peticiones automatizadas.
1000 peticiones por dia para usuarios autorizados. Es para evitar el «leeching».