Si usted quiere desarrollar con Bluevia y Java, esto es lo primero que debe saber. Presentación realizada por liminal ltda en Campus Party Colombia 2011.
www.liminal-it.com
3. LIMINAL
Si usted quiere desarrollar con Bluevia y Java,
esto es lo primero que debe saber
Mario Linares Vásquez
mario.linares@liminal-it.con
Junio
30
de
2011
4. BlueVia
Network as a Service - NaaS
Que información poseen los operadores de móviles ?
Llamadas.
Mensajes.
Network as a Service - NaaS
Ubicación de los equipos.
Per l de los usuarios y los equipos.
Facturación.
NaaS: información y servicios de la red
(network intelligence)
son ofrecidos a los usuarios y a terceros.
5. BlueVia
Telco 2.0 business model
Usuarios
Network as a Service - NaaS
Application Service Providers
APIs
Telco
6. BlueVia
Modelo de desarrollo
REST
OAUTH
SDK para Java
Documentación
AGENDA
8. BlueVia
n
e rvicios e
on sumen s
nes que c e rsonas.
aplicacio a ción de p
sa rrollo de d e inform
p ara el de jería o búsqueda
uevo c oncepto o mensa
Un n f ónica, co
m
la re d de tele
APIs y SDKs webservices REST
Diferentes lenguajes de programación.
autorización OAUTH
9. BlueVia
OAUTH
• El acceso a los recursos de la
red es autorizado por los
usuarios mediante OAUTH.
Con OAUTH, los datos identidad (login, password)
de los usuarios permanecen privados y no son
compartidos con las aplicaciones BlueVia.
10. App SDK
BlueVia
Internet
MMS
Send API MMS
Receive API SMS
SMS
Receive API Location User
Send API
API Context Advertising
API API
11. App SDK
BlueVia
Internet
MMS
REST
Send API MMS
Receive API SMS
SMS
Receive API Location User
Send API
API Context Advertising
API API
12. BlueVia
MMS MMS
App
Send API Receive API
Internet
SMS SMS
BlueVia Receive API Send API
User
Location Context Advertising
API API API
13. BlueVia
SMS Send API
SMS Receive API
MMS Receive API
MMS Send API
Advertising API
User Context API
Location API
14. BlueVia
Desarrolladores
El modelo de desarrollo, incluye
1. Registro en Bluevia: https://bluevia.com/en/user/register.
2. Obtener API Keys
15. BlueVia
Desarrolladores
Un API key es requerida por cada aplicación, con el n de usar las APIS Bluevia.
De acuerdo con el tipo de Key (Test o Comercial) las APIs se pueden utilizar en modo
SANDBOX:
Ambiente para pruebas que no
genera trá co en la red.
LIVE:
ambiente que usa la red
de telefónica de forma real.
18. BlueVia
Escenarios de desarrollo
Test API Key Commercial API Key
Sandbox Fase inicial de desarrollo Pruebas antes de iniciar el proceso de
Pruebas de la aplicación acreditación de la aplicación o antes de
Simulación de error subir a una App Store.
No genera trá co
Live Pruebas con desarrolladores registrados Transacciones sobre la red de acuerdo
y que tengan crédito con el modelo comercial seleccionado.
para uso de las APIS.
20. BlueVia
Métodos protocolo HTTP
Método (Verbo) Uso
OPTIONS Retorna los métodos soportados por el servidor
GET Solicita una representación de un recurso
HEAD Igual que GET pero sin cuerpo
POST Envía datos para ser procesados
PUT Envía una representación de un recurso
DELETE Elimina el recurso
TRACE Solicita retorno del mensaje enviado
CONNECT Convierte el request a un tunel TCP/IP
21. BlueVia
Códigos de estado HTTP
Código Descripción
1xx Información
2xx Éxito
3xx Redirección
4xx Error del cliente
5xx Error del servidor
22. BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
23. BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
Métod
o oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
HTTP oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
24. BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
Request oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
URI oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
25. BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
Versión oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
HTTP oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
27. BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
Cuerpo <tns:message>This is a text message</tns:message>
d
mensajel <tns:originAddress>
e
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
28. BlueVia
Mensaje HTTP – Request/Response
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443 Internet
<?xml version="1.0" encoding="UTF-8"?>
SMS
<tns:smsText >
<tns:address> Send API
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
HTTP/1.1 201 Created
Location: https://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022134544108250/deliverystatus
Content-Length: 0
29. BlueVia
REST Representational State Transfer.
Estilo arquitectónico para aplicaciones distribuidas.
El uso de un conjunto limitado de operaciones, con una
semántica uniforme, es su ciente para construir cualquier
tipo de aplicación.
30. BlueVia
REST Representational State Transfer.
• Los estados de un proceso pueden ser modelados como recursos.
• Información semántica sobre los pasos del proceso de negocio
están embebidos en las URIs.
31. BlueVia
CRUD Web services
Bajo el estilo REST, las operaciones CRUD son su cientes
para construir cualquier tipo de aplicación.
Método HTTP URI Uso
GET /message Consultar estado
POST /message/{id} Crear/enviar
PUT /message/{id} Actualizar
DELETE /message/{id} Eliminar
32. BlueVia
CRUD Web services - POST
Servidor
Cliente
POST /services/message HTTP/1.1
….
http://test.com/services/message
Host: test.com
El mensaje
201 Created
Location http://test.com/services/message/12345 Exito
400
Bad
request Error
500
Internal
error
33. BlueVia
URLs para APIs de Bluevia
h"ps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia
34. BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia.
• Identi cador del API.
35. BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/
requests/10001022145853108719/deliverystatus?
version=v1&alt=json
• URI de acceso a Bluevia.
• Identi cador del API.
• Operación.
36. BlueVia
URLs para APIs de Bluevia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia.
• Identi cador del API.
• Operación.
• Identi cador del recurso.
37. BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/
requests/10001022145853108719/deliverystatus?
version=v1&alt=json
• URI de acceso a Bluevia.
• Identi cador del API.
• Operación.
• Identi cador del recurso.
• Parámetros.
Mas info en
https://bluevia.com/en/knowledge/APIs.API-Guides
https://bluevia.com/en/knowledge/APIs.API-Reference
38. BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia.
• Identi cador del API.
• Operación.
• Identi cador del recurso.
• Parámetros.
Mas info en
https://bluevia.com/en/knowledge/APIs.API-Guides
https://bluevia.com/en/knowledge/APIs.API-Reference
39. BlueVia
APIs - Formatos de Mensaje
Los mensajes en métodos POST y PUT pueden enviarse utilizando XML, JSON o URL encoded:
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Content-Type: application/xml
XML
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText xmlns:tns="http://www.telefonica.com/schemas/UNICA/REST/sms/v1/"
xmlns:tns1=http://www.telefonica.com/schemas/UNICA/REST/common/v1
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.telefonica.com/schemas/UNICA/REST/sms/v1/
UNICA_API_REST_sms_types_v1_0.xsd ">
<tns:address>
<tns1:phoneNumber>52200009</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>30c8db243ad31380e90f3fd650af9351</tns1:alias>
</tns:originAddress>
</tns:smsText>
40. BlueVia
APIs - Formatos de Mensaje
JSON
POST
/services/REST/SMS/outbound/requests?version=v1
HTTP/1.1
Content-‐Type:
applicaQon/json
Host:
api.bluevia.com:443
{"smsText":
{
"address":
{"phoneNumber":
"52200009"},
"message":
"This
is
a
text
message",
"originAddress":
{"alias":
"30c8db243ad31380e90f3fd650af9351"},
}}
URL
POST
/services/REST/SMS/outbound/requests?version=v1
HTTP/1.1
Content-‐Type:
applicaQon/x-‐www-‐form-‐urlencoded
Host:
api.bluevia.com:443
address.phoneNumber=52200009&message=This+is+a+text
+message&originAddress.alias=30c8db243ad31380e90f3fd650af9351
41. BlueVia
APIs – Códigos de respuesta y error
Código Descripción
200
OK Éxito.
Respuesta
_pica
para
GET
y
DELETE
201
Created Recurso
creado
exitosamente
(POST,
PUT)
202
Accepted Solicitud
aceptada
para
procesamiento.
204
No
Content Éxito,
pero
la
respuesta
no
requiere
contenido.
Código error Descripción
400 Mensaje
request
con
formato
inválido
401 AutenQcación
requerida
403 El
servicio
no
puede
cumplir
con
la
solicitud,
violación
de
acuerdos
de
nivel
de
servicio.
404 El
servicio
no
puede
cumplir
con
la
solicitud,
violación
de
acuerdos
de
nivel
de
servicio.
43. BlueVia
OAUTH
OAUTH permite compartir recursos privados
(fotos, listas de contactos, números de cuentas,
etc) alojados en sitios, de tal forma que otras
aplicaciones los puedan utilizar sin almacenar
o solicitar las credenciales privadas.
Ejemplo:
una
aplicación
para
mensajería
SMS/MMS
por
internet
requiere
una
autorización
para
poder
realizar
la
facturación
a
nombre
del
propietario
del
número
que
envía
el
mensaje.
La
aplicación
no
es
del
proveedor
de
mensajería
44. BlueVia
OAUTH - De niciones
• Proveedor del servicio/Servidor: sitio o web services
donde se encuentran los recursos.
• Usuario : el propietario de los recursos.
• Consumidor/Cliente: la aplicación que quiere acceder
a los recursos.
• Token: mecanismo diferente a las credenciales del usuario,
que son usados para acceder a los recursos.
• Puede ser de tipo Request o Access.
45. BlueVia
OAUTH
1. Request token
Aplicación Servidor
2. Solicita autorización
3. Se autentica y da autorización para el acceso
Propietario
46. BlueVia
OAUTH
4. Access token
5. Acceso a los recursos
47. BlueVia OAUTH - Ejemplo
hDp://enviaunsms.com
EnviaUnSMS.com
Su número Enviar a
Mensaje
Ok
Un usuario quiere enviar un SMS (con cargo a su cuenta)
a través de una aplicación web
48. BlueVia OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número Enviar a
Mensaje
Ok
La
aplicación
solicita
“unathorized
request
token”
al
proveedor
del
servicio
49. BlueVia OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número Enviar a
Mensaje
Ok
La
aplicación
redirecciona
el
flujo
a
la
página
del
servicio
de
autorización
hDp://autorizando.com hDp://autorizando.
BlueVia
connect
Autorización
Userna
Passwor
50. BlueVia OAUTH - Ejemplo
EnviaUnSMS.com
BlueVia
connect
Autorización hDp://autorizando.com
Username
El
usuario
da
la
autorización
Password
EnviaUnSMS.com
BlueVia
connect
Autorización
Autoriza
a
enviaunsms.com
para
Enviar
SMSs
?
51. BlueVia OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número Enviar a
Mensaje
hDp://autorizando.com
La
aplicación
obQene
“authorized
request
token”
EnviaUnSMS.com
BlueVia
connect
Autorización
Autoriza
a
enviaunsms.com
para
Enviar
SMSs
?
52. BlueVia OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número Enviar a
Mensaje
La
aplicación
solicita
un
“access
token”
con
el
“authorized
request
token”
53. BlueVia OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número Enviar a
Mensaje
Con
el
access
token,
la
aplicación
solicita
al
servidor
del
proveedor
de
mensajería,
el
envío
del
mensaje
56. BlueVia
SDK para Java
Paquete Descripción
com.bluevia.examples Ejemplos de invocación de las APIs
com.bluevia.java.directory Clases para invocar API – user context
com.bluevia.java.gap Clases para invocar API -advertisement
com.bluevia.java.location Clases para invocar API - location
com.bluevia.java.mms Clases para invocar API - MMS
com.bluevia.java.oauth Clases para invocar API de autenticación
com.bluevia.java.sms Clases para invocar API - SMS
com.telefonica.schemas.unica.rest.* Clases generadas por Java XML binding (JAXB),
para los esquemas de los tipos.
57. BlueVia
SDK para Java - Funcionalidades
OAUTH
• Solicitar
RequestToken
y
AccessToken.
ADVERTISEMENT
• Consultar
un
Ad
• (un
Ad
se
compone
de
un
elemento
creativo
y
una
interacción).
59. BlueVia
SDK para Java - Funcionalidades
SMS/MMS
• Envío
de
SMS/MMS
a
múlRples
desRnos.
• Verificar
estado
del
envío
de
SMS/MMS:
–
La
aplicación
solicita
el
envío
de
noRficaciones
sobre
el
estado.
– La
aplicación
explícitamente
consulta
el
estado.
Posibles
estados:
DeliveredToNetwork,
DeliveryUncertain,
DeliveryImpossible,
MessageWaiQng,
DeliverdToTerminal,
DeliveryNoQficaQonUnsupported.
• Recepción
de
SMS/MMS
por
demanda
o
a
través
de
noRficaciones.
• Recepción
de
adjuntos
en
MMS.
61. BlueVia
SDK para Java - Funcionalidades
DIRECTORY/USER CONTEXT
• Consultar información personal del usuario.
• Consultar per l del usuario.
• Consultar información de la red.
• Consultar información del equipo.
LOCATION
• Consultar información de localización del equipo.
63. BlueVia
Documentación
• Guía de inicio
https://bluevia.com/en/knowledge/getStarted
• Guía del desarrollador APIs
https://bluevia.com/en/knowledge/APIs.API-Guides
• Manual de referencia APIs
https://bluevia.com/en/knowledge/APIs.API-Reference
• Documentación propia de cada SDK