Skip to content

Mobile services

Jump to bottom Edit New page
Claudio Rodriguez edited this page May 6, 2013 · 1 revision

Servicios para las aplicaciones móbiles.

Elementos Comunes

BASE

REST over HTTPS

Todas las comunicaciones seguirán, en la medida de lo posible, la metodología RESTful y serán siempre encriptadas utilizando los mecanismos standard de TLS/SSL. El path de la URL contendrá el versionado de los requests.

Localization

  • Para cambiar el idioma, insertar el mismo al inicio de la url. Ej: English -> ../en/api_v1

Parámetros

  • device_id Identifica el tipo de dispositivo móvil que realiza el pedido. Por ejemplo: iPhone, iPad, Android.
  • Request Signature Clave única de aplicación que verificará la autenticidad del pedido.
  • language, TBI, Indicará el lenguaje de los textos de respuesta.

Respuesta

  • Service Message Mensaje de contextual de respuesta. Puede indicar un error, o una alerta para el usuario.
  • HTTP Error Code Los códigos de error que indiquen fallo en el procesamiento del pedido, utilizarán el mecanismo estándar del protocolo.

Firma de Requests

  • Cada consumidor de la API (app iphone, app android, quién sabe en el futuro, etc) va a tener un api key y un api secret.
  • La API tiene un método sync: http://svn.dodici.com.ar/api/sync que devuelve el timestamp actual del server
  • Para construir el string signature:
    • Concatenar: 'api_key=' + + '&api_timestamp=' + +
    • A eso hacerle sha1
    • Para firmar un request, agregar los parámetros (con los mismos valores que los usados en el signature obviamente):
      • api_key =
      • api_timestamp =
      • api_signature =
    • Si el timestamp es más viejo que un cierto márgen (por ahora es dos minutos), con respecto al tiempo de server (sync), es invalido
    • Se puede probar el firmado de requests en http://svn.dodici.com.ar/app_dev.php/api/test - work in progress. key: abcdef. secret: 123456 (los keys y secret son dinámicos, eventualmente cargables desde el módulo admin)

Configuración

El servidor contendrá una configuración para el device y los pedidos que regulará la conección a Fansworld.tv.

Login (Fansworld)

Cuando sea requerido por los servicios, este pedido iniciará una sesión para el usuario.

  • Method POST
  • Route /login
  • Signed YES

Parámetros

  • username/email, string, email del usuario a conectar
  • ** password**, string, clave de acceso del usuario.

Respuesta

  • token
  • user, dictionary, includes ID, name, lastname & image url.

Ejemplo token = f9f662db39f758c9c106bcd59365b746d82e1500; user = { email = "[email protected]"; firstname = Juan; id = 2; image = "http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_2_default_small_1fe36b4108f01189581c85258d60282bdd947a96.jpg"; lastname = "P\U00e9rez"; username = "juan.perez"; };

Login (Facebook Connect)

Si el usuario existe y su cuenta esta asociada, realiza un login normal. En caso de estar registrado, y la cuenta no asociada a FB, asocia y realiza el login. Si, el usuario no existe, se procede a la registración del mismo.

  • Method POST
  • Route /connect/facebook
  • Signed YES

** Parámetros **

  • facebook_id, integer, email del usuario a conectar
  • access_token, string, token entregado por FB Connect en FBSession.
  • idol, array(integer), listado de id de idolos que elija seguir el usuario.
  • team, array(integer), listado de id de equipos que elija seguir el usuario.

** Respuesta **

  • token
  • user, dictionary, includes ID, name, lastname & image url.

** Ejemplo ** token = f9f662db39f758c9c106bcd59365b746d82e1500; user = { email = "[email protected]"; firstname = Juan; id = 2; image = "http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_2_default_small_1fe36b4108f01189581c85258d60282bdd947a96.jpg"; lastname = "P\U00e9rez"; username = "juan.perez"; };

Register

Crea un nuevo usuario en Fansworld.tv.

  • Method POST
  • Route /register
  • Signed YES

** Parámetros **

  • email, string, email de usuario
  • password, string, password en texto plano
  • firstname, string, nombre real del usuario
  • lastname, string, apellido real del usuario
  • idol, array(integer), listado de id de idolos que elija seguir el usuario.
  • team, array(integer), listado de id de equipos que elija seguir el usuario.

** Respuesta **

  • token
  • user, dictionary, includes ID, name, lastname & image url.

** Ejemplo ** token = f9f662db39f758c9c106bcd59365b746d82e1500; user = { email = "[email protected]"; firstname = Juan; id = 2; image = "http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_2_default_small_1fe36b4108f01189581c85258d60282bdd947a96.jpg"; lastname = "P\U00e9rez"; username = "juan.perez"; };

Password Reset

Genera una nueva password y envia una confirmación al mail del usuario.

  • Method POST
  • Route /password/reset
  • Signed YES

Parámetros

  • username/email, string, email de usuario

Respuesta

  • sent, boolean, confirmación de envio.

Ejemplo TBD

Team List

Listado de entidades de Equipos en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method GET
  • Route /team/list
  • Signed NO

Parámetros

  • country, integer, filtra por id de pais.
  • limit, integer, cantidad de elementos a incluir en la respuesta
  • offset/page, integer, cantidad de elementos por página.
  • sort, enum { fanCount, title }, ordena según la clave elegida.
  • sort_order, enum { asc, desc }, ordena ascendente o descendente.

Respuesta

  • array, listado de entidades de equipo en Fansworld.tv.

Ejemplo

({fanCount = 5; id = 1; image = "http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_7_default_small_6aefd9341d188b056d66dee2dcbd1da40c4606ac.png"; title = "All Boys";}, ...)

Team Fan / Unfan

Listado de entidades de Equipos en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method POST
  • Route /team/fan/{action} {"action" = "add|remove"}
  • Signed YES

Parámetros

  • user_id, integer, id del usuario.
  • team_id, integer, id del equipo.

Respuesta

  • BOOL, success.

Ejemplo

TODO

Idol List

Listado de entidades de Idolos en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method GET
  • Route /idol/list
  • Signed NO

Parámetros

  • country, integer, filtra por id de pais.
  • limit, integer, cantidad de elementos a incluir en la respuesta
  • offset/page, integer, cantidad de elementos por página.
  • sort, enum { fanCount, title }, ordena según la clave elegida.
  • sort_order, enum { asc, desc }, ordena ascendente o descendente.

Respuesta

  • array, listado de entidades de equipo en Fansworld.tv.

Ejemplo

({fanCount = 9; firstname = "Sergio Leonel"; id = 1; image = "http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_45_default_small_3282e5e1d1b90ad8a89cdb6374d18c0179f49214.jpg"; lastname = "Ag\U00fcero"; }, ... )

Idol Fan / Unfan

Listado de entidades de Equipos en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method POST
  • Route /idol/fan/{action} {"action" = "add|remove"}
  • Signed YES

Parámetros

  • user_id, integer, id del usuario.
  • idol_id, integer, id del ídolo.

Respuesta

  • BOOL, success.

Ejemplo

TODO

User Fan / Unfan

Si el usuario está logueado puede agregar/borrar otro usuario a su lista de fans.

  • Method POST
  • Route /user/fan/{action} {"action" = "add|remove"}
  • Signed YES

Parámetros

  • target_id int
  • user_id int
  • user token
  • signature params

Respuesta

  • BOOL, success.

Ejemplo

TODO

Fans List

Listado de fans que sigue el usuario en Fansworld.tv. No requiere que el usuario esté autenticado.

Respuesta

  • Fan List Listado de Fans.

Ejemplo

TODO

Keyword List

Listado de términos comunes utilizados en las búsquedas. No requiere que el usuario esté autenticado.

Respuesta

  • Keyword List Listado plano de términos de búsqueda.

Ejemplo

TODO

Search

Realiza la búsqueda de contenido en Fansworld.tv, con resultados adaptados al dispositivo móvil. Solo retorna videos, fotos, eventos y mensajes. No entidades.

  • Method GET
  • Route /search/term
  • Signed OPTIONAL

Parámetros

  • term Criterio para la búsqueda.

Parámetros Opcionales

  • result_types comma-separated string; possible values: video, photo, event, user, team, idol.
  • limit int (amount of entities to return, default: LIMIT_DEFAULT)
  • offset/page int (amount of entities to skip/page number, default: none)
  • imageformat string
  • user_id int, will be used for filtering
    • user_token string, user token
    • signature params

Respuesta

  • Result List Listado de videos, fotos, mensaje y eventos en Fansworld.tv.

** Ejemplo ** TODO

Notification - List

Lista notificaciones no atendidas por el usuario.

Respuesta

  • Pending Notifications Lista de notificaciones pendientes del usuario.

Ejemplo

TODO

Notification - Mark as Viewed

Marca las notificaciones como leídas, por lo que no aparecerán en los siguientes pedidos de listado.

Parámetros

  • Notification ID Identificador de la notificación.

Ejemplo

TODO

Notification - Options

Lista las posibles configuraciones para la suscripción a notificaciones.

Respuesta

  • Options El listado indicará también cuales tiene activa el usuario.

Ejemplo

TODO

Notification - Subscribe

Activa el mecanismo de notificación para el usuario.

Parámetro

  • Notification Mode ID

Ejemplo

TODO

Playlist - List

Lista los videos que el usuario seleccionó para ver en otro momento.

  • Method GET
  • Route video/playlist/list
  • Signed YES

Parámetros

  • user_id, integer, id del usuario.
  • user_token, integer, token de accesso del usuario (cacheado en login/reg).
  • [video listing params]

Respuesta

  • array, video list.

Ejemplo

TODO

Playlist - Add / Remove

Agrega o remueve videos del playlist del usuario.

  • Method POST
  • Route video/playlist/{action} {"action" = "add|remove"}
  • Signed YES

Parámetros

  • user_id, integer, id del usuario.
  • user_token, integer, token de accesso del usuario (cacheado en login/reg).
  • video_id, integer, id del video.

Respuesta

  • BOOL, success.

Ejemplo

TODO

Explore

Provee el listado de videos relacionados con el perfil del usuario.

Parámetro

  • Recommended Si este indicador está presente, el resultado es solo de videos recomendados para el perfil.
  • Page Número de página.

Respuesta

  • Video List Listado de videos unicamente

Ejemplo

TODO

Channels - List

Listado de canales en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method GET
  • Route /video/categories
  • Signed NO

Respuesta

  • array, listado de canales.

Ejemplo

({"id":"1", "title":"Historias"}, ...)

Channel - Detail

Obtiene un canal en Fansworld.tv. No requiere que el usuario esté autenticado.

  • Method GET
  • Route /video/categories/:channelID:
  • Signed NO

Respuesta

  • Channel, JSON del canal.
    • id: integer
    • title: string

Ejemplo

{"result":{"id":"4","title":"Clubes"},"metadata":{"uri":"http:\/\/svn.dodici.com.ar\/app_dev.php\/api_v1\/video\/categories\/4","method":"GET","parameters":{"query":[],"request":[]}}} # Channels - Subscribe (Un)

Agrega o reumueve un canal a la lista de suscripciones del usuario. Esto afectará el contenido de su home y sus recomendados.

Parámetros

  • Channel ID
  • Unsubscribe Indica si debe ser removida la suscripción.

Ejemplo

TODO

Capture - Add

Agrega un nuevo contenido del usuario, foto o video, a su perfil. TODO: Este método debe evolucionar hacia un mecanismo que permita la subida por partes de contenidos de gran tamaño.

Parámetros

  • Title
  • Privacy level Público o privado.
  • Data Base 64 del contenido
  • Data type Formato del contenido.
  • Tag list

Respuesta

  • Upload ID

Ejemplo

TODO

Video List

Listado de videos en Fansworld.tv. Requiere que el usuario esté autenticado, dependiendo de los filtros utilizados.

  • Method GET
  • Route /video/list
  • Signed YES (dependiendo del filtro).

Parámetros

  • recommended, boolean, si está activo trae los videos de interes para el usuario.
  • user_id, integer, requerido si recommended está activo.
  • user_token, string, requerido junto con el id de usuario.
  • highlight, boolean, si está activo solo trae videos highlight.
  • category_id, integer, filtro para incluir videos solo de una categoria.
  • extra_fields, array, enum {  author, content, createdAt, duration, visitCount, likeCount, commentCount, watchlisted, liked }. Valores adicionales bajo pedido.
  • limit, integer, cantidad de entradas en la respuesta.
  • offset|page, integer, número de pagina.
  • sort, enum { weight, createdAt }, criterio de ordenamiento. Valor por defecto: weight.
  • sort_order, enum { asc, desc }, dirección de ordenamiento. Valor por defecto: desc.

Respuesta

  • array, listado de videos.

Ejemplo

({ id : 1, title:"Video de fansworld", image":"http://svn.dodici.com.ar/uploads/media/default/0001/01/thumb_114_default_small_b45b8bfeb0e874d616d4efc78031e5b0bc5aba8a.jpg", highlight:true, category_id": 1}, ...)

Video Detail

Detalle de videos en Fansworld.tv. Requiere que el usuario esté autenticado, dependiendo de los filtros utilizados.

  • Method GET
  • Route /video/:fanswordID:
  • Signed YES (dependiendo del filtro).

Parámetros

  • recommended, boolean, si está activo trae los videos de interes para el usuario.
  • user_id, integer, requerido si recommended está activo.
  • user_token, string, requerido junto con el id de usuario.
  • highlight, boolean, si está activo solo trae videos highlight.
  • extra_fields, array, enum {  author, content, createdAt, duration, visitCount, likeCount, commentCount, watchlisted, liked }. Valores adicionales bajo pedido.
  • limit, integer, cantidad de entradas en la respuesta.
  • offset|page, integer, número de pagina.
  • sort, enum { weight, createdAt }, criterio de ordenamiento. Valor por defecto: weight.
  • sort_order, enum { asc, desc }, dirección de ordenamiento. Valor por defecto: desc.

Respuesta

  • Video Object, JSON representando la info del video.

Video Stream

Stream de un video de Fansworld.tv.

  • Method GET
  • Route /video/:fanswordID:/stream
  • Signed NO

Respuesta

  • provider, enum { 'youtube'|'vimeo'|'kaltura' }.
  • streams, youtube/vimeo id string or [url: string (stream url), format: [ id: stream format id, name: string (stream format's name), description: string (stream format's description)), bitrate: int (kb), size: int (file size in kb), width: int (px), height: int (px)] ]

Ejemplo

{"result":{"provider":"kaltura","streams":[{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/0\/video.mp4","format":{"id":0,"name":"Source","description":"Maintains the original format and settings of the file - duplicate of the source file"},"bitrate":12697,"size":251904,"width":1280,"height":720},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/5\/video.mp4","format":{"id":5,"name":"Basic - Small","description":"Basic web quality, small frame. To be used for low resource environments."},"bitrate":466,"size":9523,"width":624,"height":352},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/4\/video.mp4","format":{"id":4,"name":"Standard - Small","description":"Standard web quality, small frame"},"bitrate":824,"size":16793,"width":624,"height":352},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/3\/video.mp4","format":{"id":3,"name":"Standard - Large","description":"Standard web quality, large frame"},"bitrate":1312,"size":26828,"width":1280,"height":720},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/2\/video.mp4","format":{"id":2,"name":"High - Large","description":"High web quality, large frame"},"bitrate":1672,"size":34099,"width":1280,"height":720},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/1\/video.mp4","format":{"id":1,"name":"HD","description":"High Definition"},"bitrate":3773,"size":77004,"width":1280,"height":720},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/301971\/video.mp4","format":{"id":301971,"name":"iPad","description":"iPad"},"bitrate":1446,"size":29491,"width":1024,"height":576},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/301991\/video.mp4","format":{"id":301991,"name":"Mobile (3GP)","description":"Nokia\/Blackberry"},"bitrate":361,"size":7362,"width":320,"height":176},{"url":"http:\/\/www.kaltura.com\/p\/1164832\/sp\/0\/playManifest\/entryId\/0_6mmixyh1\/format\/url\/flavorParamId\/301951\/video.mp4","format":{"id":301951,"name":"Mobile (H264) - Basic","description":"iPhone,android"},"bitrate":466,"size":9512,"width":480,"height":256}]},"metadata":{"uri":"http:\/\/svn.dodici.com.ar\/app_dev.php\/api_v1\/video\/1\/streams?api_key=abcdef&api_signature=5f349f0589aa86386774ce7cc3c094235eb7fc90&api_timestamp=1357735641&device_id=iPhone%20Simulator","method":"GET","parameters":{"query":{"api_key":"abcdef","api_signature":"5f349f0589aa86386774ce7cc3c094235eb7fc90","api_timestamp":"1357735641","device_id":"iPhone Simulator"},"request":[]}}} # Share

Comparte los elementos que ya existen en alguna entidad de Fansworld.tv.

Parámetros

  • Element ID
  • Message
  • Privacy level
  • Share On Indica si debe ser compartido en Facebook, Twitter o Fansworld.tv.

Ejemplo

TODO

Event - Check In

Registra al usuario al evento, a partir de lo cual puede participar activamente en el mismo.

Parámetros

  • Event ID
  • Location Información de localización del usuario.
  • Team Indica a qué equipo está alentando el usuario.

Ejemplo

TODO

Event - Status

Da información del estado del evento. El mismo puede estar pendiente de comenzar, en transcurso o finalizado.

Parámetros

  • Event ID

Respuesta

  • Status Info Información del estado y marcador del evento. Horario de comienzo, etc.

Ejemplo

TODO

Profile

Da información del perfil del usuario actualmente conectado en el dispositivo.

Respuesta

  • Badge list
  • Fans list

Ejemplo

TODO

Liked

Setea el parametro "Like" en lo opuesto a lo que estaba

  • Method POST
  • Route /{entitytype}/{id}/like/{action}
    • entitytype = "video|photo|comment"
    • id = int
    • action = "add|remove"
  • Signed YES

Parámetros

  • user_id int
  • user token
  • signature params

Respuesta

  • like boolean, confirmación de envio.
  • likecount int, nuevo valor.

Ejemplo TBD

Códigos de Error

Posibles respuestas de error.

Add a custom footer
Add a custom sidebar
Clone this wiki locally