Over the cloud: AppEngine

In this case study, we show how simple it is to implement a web service gathering incoming SMSs and posting them at social networks such as Twitter or Facebook. We use Google AppEngine as platform as a service, bringing BlueVia APIs to the cloud. For this example, raw APIs are invoked without any SDK, programing servlets with Java, a little bit of JSP, CSS and HTML.

Introduction

Applications development for mobile architectures challenges software engineers and developers with new requirements. Platform as a service, i.e. PaaS, is becoming popular thanks to fast deployment of web services, scalability and fault tolerance. Costs, application services provided or the programming language supported are driving factors.

One of the most popular is Google App Engine, offering a freemium model, supporting Java, Python or Go, and probably most important, integrating Google Accounts for user authentication. For this case study, it will be our PaaS and Java, the programing language. You can find the source code, licensed under Apache 2.0, at GitHub.

Sign-Up process and API key request

Our web application integrates two different APIs/services: BlueVia, a network as a service APIs, and App Engine, a platform as a service. In order to get access to these services, the developer needs to sign-up before, getting also APIs keys for BlueVia. For BlueVia, the process begins here.

After that, you will be a new member of BlueVia community. A BlueVia account gives you lots of useful information, including APIs usage and earnings dashboard, other case studies or some of the coolest reports about mobile development such as Developer Economics Report or Mobile Dev Guide to the Galaxy Once. But now, we only need to get the APIs keys for our application.

Requesting the APIs keys is quite simple: only few details about your application and the APIs requested are needed. Let’s see them:

1. First, decide a name for your app. A short description is always welcomed. Remember that this information will be shown to your customer, so you should follow a minimal guidelines for marketing. Optionally, you can submit an icon as well.
2. Second, select which APIs you want to use in your app. Take a look of all of them here. For this example, we only need SMS MT/MO APIs (sending and receiving). BlueVia provides you with a free short number per country but, in order to be able to receive incoming SMSs, you have to provide an application keyword. This allows BlueVia to identify your incoming messages, delivering them to your application.
3. Finally, depending on the way you gather the incoming SMSs (MO SMS), you should provide an application certificate. In our case study, we will use pulling and pushing mechanism, so you have to provide a valid certificate for Google App Engine. See here how to get one.

And that’s it. You’ve already got your API keys. Please, keep this important information save & safe. BlueVia authenticate APIs invocation with oAuth 1.0. API key & secret and Environment URLs are used in this authentication process. Depending on the APIs, the authentication process follows 2-legged or 3-legged oAuth. You can get more information about the process here. There are examples of both oAuth processes below.

Concerning the platform as a service, App Engine offers a good mix of low level & high level resources, supporting Java, Python and Go programming languages, Eclipse plug-in or a multi tenant architecture. Finally, the authentication support for Google users, smooth the UX for millions of customers. So it is a good starting point if you want to use a PaaS. Furthermore, you can get access just with your Google Account. Take a look of App Engine at Google Developer site to get ready with App Engine, and do not forget to create an account here for Internet deployment.

So after these few steps, we already have Google App Engine credential (GMail account), BlueVia credential and API key for the apps. Therefore it is time to start to program.

User Interface

User interface is the starting point for any user. This app is rather simple, so it does not have many interfaces. We have to program a main web site where the user sign in, using its Google credentials, and where you will have:

• A menu interface allowing users to:
  • Delete their account
  • Configure their connection with:
    • BlueVia
    • Twitter
    • Facebook
  • Sign out
• Two information box:
  • With information about your personal profile
  • Last four messages received for the application
• One form allowing the user to post text at BlueVia i.e. delivering SMS on behalf of him, post the same text at Twitter and Facebook.

Take a look below how some of these user interfaces look:

Backend

The backend implements the behavior of the application using a computational abstraction called serlvets. These are just functional units, server extensions, behind a name i.e. a URL. Therefore every feature of the application is accessible through a URL and hence every http request, whatever method used, is attended by the specific servlet. App Engine follows this servlet architecture for every behavior, even for backend threads i.e. those not serving any user request. Thus, the application contains servlets attending user requests and accessory ones i.e. those which implements support processes.

Taking a look into the file index.jsp, you can find the connection between JSPs i.e. user interfaces and those servlets serving user requests:

• Settings:
  • URI:/settings
  • File:settings.jsp
• SendSMS
  • URI:bluevia/send-sms
  • File:SendSMS.java
• OAuth
  • URI:/oauth?network=bluevia&step=1)
  • File:OAuth.java

As previously mentioned, there is also an important servlet which is not attending any interaction with users. It is used for the initialization: InitService (file InitService.java. Finally, you might also find another servlets serving RemoveUser or testing, but these are not important, so I won’t explain them. You can find the whole set of files at GitHub. However, we will explain carefully the Java class Util, file Util.java, where we have programmed many utilities for the program.

Therefore, the starting point is to describe this binding between URls (names) and servlets. This is done in a file named web.xml and its structure is quite simple. First, we specify which file is served under the base domain i.e. in our case, https://net-bluevia.appspot.com.

Every servlet should have the following minimum set of parameters:

• Servlet, including its name and class
• Servlet mapping, including its name and its URL

As an example, below you have the description of the OAuth serlvet, attending authentication request from the users. The xml data structure simply connects a servlet class with an url pattern.

In closing this part there are just a few additional comments: the notification URI, i.e. the URI that BlueVia will use to notify the reception of incoming SMS, has to be secured. This is very important to avoid security issues. For this reason, we will use HTTPS protocol for the request & response. This can be done just specifiying a user data constraint that make https mandatory.

Finally, as we said, there is a special servlet for initialization. App Engine uses this approach to offer backend process in a familiar way for web developers. It is implemented as another servlet but with a specific url-pattern attribute: /_ah/start. That means that the platform will call this servlet as part of the initialization process. The code can run and never ending loop, for instance to implement pulling, or it can be use only for initialization, registering the URIs for the notification. In addition, you have to specify the infrastructure behind this backend process i.e computational resources. This will be done at backend.xml

Backend initialization: SMSs MO

As we already have said, the initialization process is implemented by InitService. You can take a look of the source code for this servlet in the file InitService.java. Basically this servlet does the following:

• Implement a request strategy for SMS MO i.e. decide how to receive incoming SMS: pulling or pushing
• Register a hook for the uninstallation. This is only for pushing strategy and it is needed because once you have register the notification URLs, the platform save it till you unsubscribe them.

The notification process has three steps:

1. At booting your service, the application can subscribe endpoints which will be used by the platform when BlueVia receive SMSs for your service. Following the operation described in the figure, you have to provide:
   1. Correlator: a random string with less than 20 characters. With this, BlueVia platform build the unsubscribing URL, appending your correlator to the base URI.
   2. Endpoint: the URI of your service which BlueVia will call on incoming SMSs. It has to be a secure URI i.e using https. The certificate for this secure server should have been submitted during the APIs key request.
   3. PhoneNumber: this is the short number to which you are subscribing. Remember that you have the whole list of short number provided here. You have to subscribe to all those number from which you want to receive SMSs. Obviously, you can use the same URI for all of them.
   4. Criteria: this is the keyword which BlueVia will use to filter your incoming SMSs
2. Then, if BlueVia receives an incoming message for your application, you will receive a http call, POST method, at you previously subscribed endpoint. You can find the java code processing this request at ReceiveSMS servlet, in the file ReceiveSMS.java. If you take a look of the figure below, take into account that some of the parameters included in the json data structure depends on the values you submitted before, at the step 1.

1. Finally, in the case you decide to uninstall your application, you should unsubscribe your endpoints. To do that, you need to get back the unsubscription URL obtained at the step 1. For that reason, the application saved them using the storage service. Basically, this URI is formed by a base part (fixed by BlueVia) and the correlator, provided by you.

Authentication: 2-legged & 3-legged oAuth

In this section, we describe the authentication process for BlueVia. For the authentication at Twitter or Facebook, you have the source code included with the project, but if you need more details, you will have to take a look at information about authentication process in their websites. Concerning BlueVia, you can find all the information about BlueVia oAuth process at here.

As we have mentioned before, this case study include two variations of oAuth 1.0 process: 2-legged & 3-legged. In any case, we will use Signpost oAuth library for Java. It is dead simple, GAE compatible, support oAuth 1.0. It is open source and you can find it here. Shortly described 2-legged oAuth authenticate interactions between two systems: the BlueVia API platform and your application. In this case, you only need the consumer token that you got it requesting the BlueVia API keys. Instead, 3-legged oAuth authenticate the interaction of two system, one of them acting on behalf of the user: in our case, the user, your application and the BlueVia API platform. In this case, you will need the consumer token and the access token. Let us see how to get the access token.

If your application calls BlueVia APIs on behalf of the user, you will need to get the access token before. The process is mandatory but it needs to be run just one time per user. It a simple process following the next chart:

All this process is implemented in the function oAuthBlueVia, in the file oAuth.java. We use the same function that depending of the url parameter “step” process different part of the oAuth sequence (also called oAuth dance). Following the previous diagram, you can see starting at the line 18 the java sentences getting the request token. That means only to build an URL properly configured with authentication parameters, redirecting the user to the authentication server. BlueVia has its own authentication server, accessible here.

Once the user’s credentials are validated by the authentication server, and using the request token obtained, the function request the access token (see line between 24-40). Consumer token and access token are the tokens needed for 2-legged and 3-legged oAuth. We will keep them safe for future uses in the storage service.

And that is it. Although if you use SMS or Out of Band authentication, it is slightly different, but as always, you can find the details in the oAuth tutorial.

Once you have your consumer token and your access token, you will have to use them properly depending on the kind of oAuth process neeeded. Let’s see an example of 2-legged in the code of the function doUnsubscribeNotifications, included in the file Util.java. As you can see there, only the consumer token is used.

Otherwise, if you need to call the APIs on behalf of the user, for instance sending SMSs, then you have to follow 3-legged oAuth authentication. In this situation, you have to use both consumer and access token in the OAuth process. The consumer token identifies your application while access token identifies the user. You can see an example of this in the function sendBlueViaSMS, in the file SendSMS.java:

Delivering SMS

After configuration of the servlet application, initialization of the backend and basic oAuth configuration, the last feature we will show you is how to deliver SMSs on behalf of the user. Using the UI, the user can send text to other users in very simple way. We saw the details of the user interfaces above, so let’s take a look of the programming details:

Again, the process is quite simple. It is only needed to fulfill the json structure with the parameters of the operations:

1. PhoneNumber is the destination phone number. Remember that it has to provide it with the international code. In any case this is an information requested to the user.
2. Message: 160 characters limited message and again, the user will provide it.
3. Alias is the the user identifier. The platform uses the access key, but this value allow BlueVia to get the phone number back and it will be shown as origin of the text.

This time, the operation is 3-legged oAuth, so you will need to sign the HTTP request using both consumer and access tokens. You can take a look of the source code below. As you can see, we don’t use any json library in this case. It is so simple that it doesn’t worth.

Conclusion

During this case study, we have presented a interesting solution implementing raw calls to BlueVia APIs. This allow you to deploy web services using Google App Engine. This is always a powerful resource for those developers programming on platforms which don’t have BlueVia SDKs. You have seen how simple this can be, and we hope you find the case study useful.

Do you want go further? Developers know very well that source code is the better documentation, so If you have any questions, you can find the whole project at GitHub. More questions? Just get in touch.