SMS REST API Developers Guide

Embed Size (px)

Citation preview

Gua del API SMS REST

Pgina 1 de 27 movistar 2009 Reservados todos los derechos.

Contenido1 INTRODUCCIN ................................................................................................................... 4 1.1 ALCANCE ...................................................................................................................... 4 1.2 GLOSARIO .................................................................................................................... 5 2 CONVENCIONES GENERALES ........................................................................................... 6 2.1 PAUTAS GENERALES DE UNA INTERFAZ REST ..................................................... 6 2.2 CONSIDERACIONES ESPECFICAS PARA LA API REST DE SMS .......................... 6 2.2.1 Consideraciones de Seguridad ................................................................................. 8 3 DEFINICIN DE LAS OPERACIONES ............................................................................... 10 3.1 ENVO DE SMS........................................................................................................... 10 3.1.1 Peticin .................................................................................................................... 10 3.1.2 RESPUESTA ........................................................................................................... 11 3.2 CONSULTA DEL ESTADO DE ENVO ....................................................................... 12 3.2.1 PETICIN ................................................................................................................ 12 3.2.2 4 5 Respuesta ............................................................................................................... 13 NAMESPACES .................................................................................................................... 15 DEFINICIN DE TIPOS DE DATOS ................................................................................... 16 5.1 ESTRUCTURA DEL SMSTextType ............................................................................ 16 5.2 ESTRUCTURA DEL SMSTextResultType .................................................................. 16 5.3 ESTRUCTURA DEL SMSDeliveryStatusPollType ...................................................... 16 5.4 ESTRUCTURA DEL SMSDeliveryStatusType ............................................................ 17 5.5 ESTRUCTURA DEL DeliveryInformationType ............................................................ 17 5.6 ENUMERACIN DEL DeliveryStatusType ................................................................. 17 5.7 ENUMERACIN DEL AltType .................................................................................... 18 5.8 OPCIN UserIdType ................................................................................................... 18 6 LIBRERAS CLIENTE DE USO DE LAS APIS .................................................................... 19 6.1 CLIENTE JAVA ........................................................................................................... 19 6.1.1 Directrices de Programacin ................................................................................... 19 6.1.2 6.1.3 6.1.4 Ejemplo para el envo con el cliente SMS ............................................................... 19 Paquetes del Cliente ............................................................................................... 20 Prerrequisitos .......................................................................................................... 21

6.2 CLIENTE C# ................................................................................................................ 21 6.2.1 Directrices de Programacin ................................................................................... 21 6.2.2 6.2.3 6.2.4 Ejemplo para el envo con el cliente SMS ............................................................... 21 Paquetes del Cliente ............................................................................................... 22 Prerrequisitos .......................................................................................................... 22

6.3 CLIENTE PHP ............................................................................................................. 22 6.3.1 Dependencias .......................................................................................................... 22 6.3.2 6.3.3 6.3.4 7 A Directrices de Programacin ................................................................................... 22 Ejemplo para el envo con el cliente SMS ............................................................... 22 Paquetes del Cliente ............................................................................................... 23

DETALLE DE LAS DESCRIPCIONES DE ERROR ............................................................ 24 CONSIDERACIONES GENERALES ................................................................................... 25 A.1 Mtodos HTTP ............................................................................................................ 25 A.1.1 POST ....................................................................................................................... 25 A.1.2 A.1.3 A.1.4 GET ......................................................................................................................... 25 PUT.......................................................................................................................... 25 DELETE ................................................................................................................... 26

A.2 REPRESENTACIONES COMUNES ........................................................................... 26 A.2.1 JSON ....................................................................................................................... 26

Pgina 2 de 27 movistar 2009 Reservados todos los derechos.

A.2.2 B

XML ......................................................................................................................... 26

REFERENCIAS .................................................................................................................... 27

Pgina 3 de 27 movistar 2009 Reservados todos los derechos.

1 INTRODUCCINEste documento sirve como gua para el uso de la API REST de envo de SMS que proporciona Movistar Developers PlatformBETA. Las funcionalidades que se exponen son el envo de SMS y la consulta del estado de envo de un SMS. Estas funcionalidades se exponen a travs de una interfaz REST (REpresentational State Transfer) que expone el servicio simplificando las peticiones a travs de sencillas peticiones HTTP. 1.1 ALCANCE

El API SMS de Movistar Developers PlatformBETA permite el envo de mensajes SMS a los siguientes pases. ALEMANIA ARGENTINA BRASIL COLOMBIA CHILE CHINA ECUADOR EL SALVADOR ESPAA ESTADOS UNIDOS FINLANDIA FRANCIA HONK KONG INDIA IRLANDA ISRAEL ITALIA JAPN KOREA DEL SUR GUATEMALA MARRUECOS MXICO NICARAGUA PASES BAJOS PANAM PER PORTUGAL REINO UNIDO REPBLICA CHECA RUSIA SUECIA

Pgina 4 de 27 movistar 2009 Reservados todos los derechos.

TAIWN URUGUAY VENEZUELA

1.2

GLOSARIO API: Application Programming Interface ID: Identifier HTTPS: HyperText Transfer Protocol Secure JSON: JavaScript Object Notation REST: Representational State Transfer SMS: Short Messaging Service URI: Uniform Resource Identifier URL: Uniform Resource Locator WSDL: Web Services Description Language XML: eXtended Markup Language

Pgina 5 de 27 movistar 2009 Reservados todos los derechos.

2 CONVENCIONES GENERALES2.1 PAUTAS GENERALES DE UNA INTERFAZ REST REST (REpresentational States Transfer) es un estilo de arquitectura basado en los siguientes principios: Direccionabilidad: Los recursos son expuestos mediante URIs. Sin Estado. Las peticiones a los recursos son independientes una de la otra. Conectividad. Los recursos pueden incluir enlaces a otros recursos. Una interfaz uniforme: Las operaciones permitidas son obtencin, creacin, modificacin y eliminacin de recursos utilizando el protocolo HTTP.

La implementacin de estos pilares da como resultado servicios RESTful que se basan en el protocolo HTTP, son independientes del lenguaje, pueden usarse en presencia de firewalls, las aplicaciones pueden cachearlos, son altamente escalables, etc. REST tiene como propsito la implementacin de servicios ligeros, inteligibles y fcilmente implementables que se definen en base a una serie de operaciones RESTful, que implica el intercambio de informacin acorde a los formatos de los datos REST. 2.2 CONSIDERACIONES ESPECFICAS PARA LA API REST DE SMS 1. La peticin de envo de SMS es una peticin POST que se puede hacer con los siguiente Content-Types: - application/xml - application/json - application/x-www-form-urlencoded (soportado, aunque se recomienda usar XML o JSON) 2. La respuesta a esa peticin ir en el formato expresado en la peticin, excepto cuando la peticin sea url-encoded, en cuyo caso las respuestas sern XML. 3. La peticin de SMSDeliveryStatus es una peticin GET, en la que se indica el SMS a consultar a travs de un parmetro indicado en la URI que forma la peticin. Por defecto la respuesta tiene formato XML, aunque se puede pedir que la respuesta est en formato JSON a travs de un parmetro alt, incluido en la URI que forma la peticin. 4. Mapeo de XML A JSON. Puesto que XML es el formato por defecto utilizado en la API de SMS, se incluyen archivos XSD que describen los datos necesarios para invocar al API mediante XML. Para pasar estas representaciones a formato JSON, se presentan las siguientes reglas de aplicacin general:a. Los elementos XML que aparecen al mismo nivel jerrquico XML (tanto los elementos de primer nivel como los que estn dentro del mismo elemento XML padre), se mapean a un conjunto de pares nombre:valor dentro de un objeto JSON, como se describe a continuacin:Pgina 6 de 27 movistar 2009 Reservados todos los derechos.

i. Cada elemento XML que aparece una sola vez en el mismo nivel jerrquico se mapea a un par nombre:valor individual. El nombre se forma de acuerdo al punto b, mientras que el valor se forma de acuerdo al punto c. ii. Elementos XML que aparezcan ms de una vez en el mismo nivel jerrquico se mapean a un nico par nombre:valor individual. El nombre se forma de acuerdo al punto b, mientras que el valor is un array JSON que contiene un valor por cada ocurrencia del elemento XML. El nombre se forma de acuerdo al punto b, mientras que los valores se forman de acuerdo al punto c. iii. El nombre y el valor de los objetos JSON irn entre comillas . Adems, cualquier representacin JSON ir entre llaves {}, de acuerdo a la RFC de JSON. b. El nombre del par nombre:valor es el nombre de los elementos XML (nombre_elemento_XML:valor). c. El valor se forma como se describe a continuacin: i. Cuando el elemento XML no tiene ni atributos ni elementos XML hijos, el valor es igual al valor del elemento XML. En caso de que el elemento sea nulo (no tenga valor), se indicar poniendo un valor null en el JSON. ii. Cuando el elemento XML tenga elementos hijos y/o atributos, el valor es un objeto JSON que contiene los siguientes pares nombre:valor : Un par nombre:valor por cada atributo, donde el nombre es el nombre del atributo y el valor es el valor del atributo. Un par nombre:valor asociado al valor del elemento XML, donde nombre es la cadena $t y valor es el valor del elemento XML.

Nota: no hay una regla especfica sobre esto en la RFC de JSON o en json.org. Por tanto, se ha seleccionado la cadena $t en base a las reglas de Google para conversin de feeds XML a JSON (http://code.google.com/intl/es/apis/gdata/json.html). Pares nombre:valor asociados a elementos XML hijos. Estos pares nombre:valor se forman de acuerdo al punto a.

Dentro de JSON no es necesario reflejar:i. ii. El primer tag

6.3.4

Paquetes del Cliente

Se describen los paquetes

Enumeracin

smsRESTlibraryXML.php smsRESTlibraryJSON.php smsRESTlibraryURLEnc.php

Descripcin Paquete que contiene la clase principal para el cliente SMS REST API con codificacin XML. Paquete que contiene la clase principal para el cliente SMS REST API con codificacin JSON. Paquete que contiene la clase principal para el cliente SMS REST API con codificacin URL encode.

Pgina 23 de 27 movistar 2009 Reservados todos los derechos.

7 DETALLE DE LAS DESCRIPCIONES DE ERRORLas operaciones descritas en esta gua pueden devolver una serie de cdigos de error HTTP, como se explica a continuacin.En caso de producirse algn error relacionado con: spId o serviceId no vlidos spPassword no vlido La aplicacin no tiene permisos para utilizar el API Parmetros no vlidos Violacin de los SLA

se responder con un cdigo de estado HTTP del tipo 4XX/5XX. Sin embargo, si de produce un error relacionado con: token no vlido El MSISDN no tiene permisos para utilizar el API

se responder con un cdigo de estado HTTP 201, pero al consultar el estado del envo se obtendr el valor DeliveryImpossible.

Pgina 24 de 27 movistar 2009 Reservados todos los derechos.

A

CONSIDERACIONES GENERALES

En esta seccin se describen elementos necesarios para el normal funcionamiento de la API REST SMS: Mtodos HTTP: que constituyen las operaciones RESTful, de acuerdo con los principios REST. Representaciones comunes.

A.1

Mtodos HTTP

Las siguientes descripciones se han extrado de la RFC de HTTP 1.1.

A.1.1

POST

El mtodo POST se utiliza para solicitar que el servidor de origen acepte la entidad contenida en la peticin como un nuevo recurso identificado por la URI de la peticin en la Request-Line. POST est diseado para permitir un mtodo uniforme que cubra las siguientes funciones: Anotacin de recursos existentes. Postear un mensaje en un boletn, grupo de noticias, lista de correo, o grupo similar de artculos. Proveer un bloque de datos, como el resultado del envo de un formulario, para que sea procesado. Extender una base de datos a travs del aadido de una operacin.

La actual funcionalidad desarrollada por el mtodo POST est determinada por el servidor y es usualmente dependiente de la Request-URI. La entidad posteada est subordinada a esa URI de la misma manera que el archivo est subordinado al directorio que lo contiene, un artculo de noticias est subordinado a un grupo de noticias al que est posteado, como un registro est subordinado a una base de datos.

A.1.2

GET

El mtodo GET intenta extraer cualquier informacin (en la forma de una entidad) identificada por una Request-URI. Si la Request-URI se refiere a un proceso que genera datos, es un dato producido que debe devolverse como la entidad en la respuesta y no el texto origen del proceso, a no ser que el texto sea la salida del proceso.

A.1.3

PUT

El mtodo PUT solicita que la entidad contenida sea almacenada bajo la Request-URI proporcionada. Si la Request-URI se refiere a un recurso existente, la entidad contenidaPgina 25 de 27 movistar 2009 Reservados todos los derechos.

debe ser considerada como una versin modificada del recurso residente en el servidor. Si la Request-URI no apunta a un recurso existente, y la URI es capaz de ser definida como un nuevo recurso por el agente solicitante, el servidor de origen puede crear el recurso con esa URI.

A.1.4

DELETE

El mtodo Delete solicita que el servidor de origen borre el recurso identificado con la Request-URI. Este mtodo puede ser reescrito por intervencin humana (u otros mtodos) en el servidor de origen. El cliente no puede garantizar que la operacin haya sido llevada a trmino, incluso si el cdigo de estado devuelto desde el origen indica que la accin ha sido completada con xito. Sin embargo, el servidor no debe indicar una respuesta satisfactoria a no ser que, en el momento en que la respuesta es entregada, intente borrar el recurso o moverlo a una localizacin inaccesible.

A.2A.2.1

REPRESENTACIONES COMUNESJSON

Las peticiones POST pueden incluir datos en formato JSON. Las respuestas deben incluir el cuerpo en formato JSON, si corresponden a peticiones POST incluidas en formato JSON o si corresponden a peticiones GET incluidas con el parmetro alt=json. En estos casos, la cabecera Content-Type:Application/json debe estar presente en la respuesta.

A.2.2

XML

Las peticiones POST pueden incluir datos en formato XML. En estos casos, se utiliza un cuerpo application/xml. Este formato XML debe cumplir con las especificaciones de XML Schema. Las respuestas deben incluir un cuerpo del XML si la correspondiente peticin POST incluye datos en formato XML o si la correspondiente peticin GET no inclua el parmetro alt=json. En estos casos, la cabecera Content-Type: Application/xml debe estar presente en la respuesta.

Pgina 26 de 27 movistar 2009 Reservados todos los derechos.

B

REFERENCIAS

[1] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common [2] 3GPP TS 29.199-4: "Open Service Access (OSA); Parlay X Web Services; Part 4: Short Messaging". [3] [4] GSMA OneAPI, http://gsma.securespsite.com/access/default.aspx RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1

[5] W3C Recommendation (26 June 2007): "Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts, https://www.w3.org/TR/2007/REC-wsdl20adjuncts-20070626/#_http_binding_default_rule_method [6] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes", http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.

Pgina 27 de 27 movistar 2009 Reservados todos los derechos.