We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Open RESTful SMS-MMSEnablers API Specification - FIWARE Forge Wiki

Open RESTful SMS-MMSEnablers API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the S3C SMS/MMS API

SMS/MMS API

The S3C SMS API are to be developped on the GSMA OneAPI V3 Specifications. It allows you to easily send short messages from any application or Web Browser. This implementation of the OneAPI SMS API v3 meets the RESTFull specification standards. It can use two different network gateways:

- Another SMS enabler
- Kannel Open Source SMS gateway (a generic SMS-C gateway)

The S3C MMS API are to be developped on the GSMA OneAPI V3 Specifications. It allows you to easily send short multimedia messages from any application or Web Browser. This implementation of the OneAPI MMS API v3 meets the RESTFull specification standards. It can use two different network gateways:

- Another MMS enabler
- Kannel Open Source SMS gateway (a generic SMS-C gateway)

Intended Audience

This specification is intended for both software developers and reimplementers of this API. For the former, this document provides a full specification of how to use the API, ie send and receive SMS/MMS. For the latter, this specification provides a full specification of how to provide a code fully supporting the protocol described in the GSMA OneAPI portal.

In order to use this specifications, the reader should firstly have a general understanding of the appropriate Generic Enabler(s) supporting the API (FIWARE.OpenSpecification.I2ND.S3C).

API Change History

This version of the API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
March, 2013 initial version
April, 17, 2013 moved installation information, added extract of OneAPI specifications
April, 19, 2013 add MMS specification, added extract of OneAPI specifications

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at FIWARE.I2ND.S3C SMS+MMS Enabler Open Specification. For more details about the S3C GE that this API is based upon, please refer to FIWARE.I2ND.S3C Open Specification.

Legal Notice

Please check the following Legal Notice to understand the rights to use FI-WARE Open Specifications.

General SMS/MMS API Information

Resources Summary

Please refer to the GSMA OneAPI V3 Specifications.

Representation Format

The SMS/MMS API supports JSON format.

Resource Identification

The resource identification used by this API is based on the URI scheme described by HTTP protocol specification as defined by IETF RFC-2616 ( https://www.ietf.org/rfc/rfc2616.txt )

OneAPI SMS may be accessed via a RESTful API. A RESTful API utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state. HTTP POST, GET and DELETE commands are used in OneAPI SMS. The URIs of the resources are:

  • Sending SMS:

Resource URI http://example.com/smsmessaging/v1/outbound/{senderAddress}/requests HTTP Method POST

  • Receiving SMS:

Resource URI http://example.com/smsmessaging/v1/inbound/registrations/{registrationId}/messages HTTP Method GET

OneAPI MMS may be accessed via a RESTful API. A RESTful API utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state. HTTP POST, GET and DELETE commands are used in OneAPI MMS. The URIs of the resources are:

  • Sending MMS:

Resource URI http://example.com/messaging/v1/outbound/{senderAddress}/requests HTTP Method POST

  • Receiving MMS:

Resource URI http://example.com/messaging/v1/inbound/registrations/{registrationId}/messages HTTP Method GET


For more detailed specifications please refer to the OneAPI web site.

Links and References

Some responses may contais reference to other resources managed by the enabler. Those links are represented as a standard URL tagged with the word “resourceURL” (see example below)

Example of links provided in an operation response (provided by GSMA OneAPI V3 Specifications):

"deliveryInfoList" : {
   "deliveryInfo" : [
       { "address" : "tel:+13500000991",
         "deliveryStatus" : "MessageWaiting" },
       { "address" : "tel:+13500000992",
         "deliveryStatus" : "MessageWaiting" },
   ],
   "resourceURL": "http://example.com/smsmessaging/v1/outbound/
       tel%3A%2B12345678/requests/abc123/deliveryInfos"
   },

Limits

The list of normal response code(s) and the list of error response code(s) is listed by GSMA OneAPI V3 Specifications.

Versions

The version of the SMS API is embedded in the server root path e.g.

https://localhost/smsV3/

Extensions

There are no extention available on this enabler.

Faults

Synchronous and Asynchronous faults are described in GSMA OneAPI V3 Specifications.

API Operations

SMS

In the following section, we just list the different operations that are allowed by the enabler. Thes operations are listed on the GSMA OneAPI V3 Specifications.

Send SMS

Query SMS delivery status

Start subscription for SMS delivery status

Stop subscription for SMS delivery status

Receive SMS

Start subscription for SMS receipt

Stop subscription for SMS receipt

MMS

In the following section, we just list the different operations that are allowed by the enabler. Thes operations are listed on the GSMA OneAPI V3 Specifications.

Send MMS

Query MMS delivery status

Start subscription for MMS delivery status

Stop subscription for MMS delivery status

Receive MMS message list

Receive full MMS message (content)

Start subscription for MMS receipt

Stop subscription for MMS receipt

Technical Specifications

Architecture Overview

The enabler is designed to be called from any Javascript client that can send HTTP requests following the specifications of GSMA OneAPI V2 SMS and MMS Rest sepcifications. On the following picture one can see a Javascript Client. This is not a part of the enabler, but illustrates one of the possibilities of use of the enabler. In this case, to simulate the notification possibilities, a polling system will be designed, from the client application.


Detailed Architecture

One the following picture, we can see that the SMS/MMS enabler following OneAPI rules embed some persistance. When sending a message, you can register to notification service. In this case, the notification url will be stored with the given id of the message. Then when the message is delivered, you are notified with the success/unsuccess message.

Kannel Connector

The Kannel connector allows the SMS enabler to connect to a Kannel gateway. Kannel is a compact and very powerful open source WAP and SMS gateway, used widely across the globe both for serving trillions of short messages (SMS), WAP Push service indications and mobile internet connectivity (see http://www.kannel.org/). By using this gateway, we can take benefit of this and easily connect to any kind of SMS-C, or even a 3G Key to simulate the network.


Interfaces to implement

  • Outgoing requests (create, get)
  • Subscriptions to delivery notifications (create, delete)
  • Request delivery status (get)
  • Subscriptions to reception notifications (create, delete)
  • Ingoing messages (get)

+ Necessity to provide notification handlers (HTTP server)


The folowing lines are extracted of the OneAPI SMS Specifications (http://www.gsma.com/oneapi/sms-restful-netapi and http://www.gsma.com/oneapi/mms-restful-netapi) and are under Copyright © 2013 GSMA.

Personal tools
Create a book