App Inventor API

TinyWebDB is an App Inventor component that allows you to access the web from an Android app. You can use TinyWebDB to access a data source (API) or to store the app’s data persistently in a web database. These notes show you how to do the former– create an App-Inventor-compliant API that returns data to an App Inventor app. Often, the service you write will just serve as a proxy and call some other existing data service (e.g., Twitter, Amazon, Yahoo Finance).

Though you can create an App-Inventor-compliant API in many languages and environments, these instructions describe an API written in Python and using Google’s free App Engine cloud-computing service. We plan to provide other samples (Java/App Engine, PHP) soon.

To follow these instructions, you’ll need to have some programming expertise and be familiar with Python and web services (APIs).

Sneak Peak

def get_value(self, tag):

value=”hello:”+tag
value = “\””+value+”\””

if self.request.get(‘fmt’) == “html”:

WriteToWeb(self,tag,value )

else:

WriteToPhone(self,tag,value)

To create your own service, you’ll simply replace the emphasized lines with whatever code you’d like. Maybe you’ll call another web service and relay the data to the app. Maybe you’ll perform some computations. You can do anything, the only restriction being that you set the variable “value” to a string or a list. The data you place in “value” is sent to the requesting app on a TinyWebDB.GetValue request.

Note that the cryptic line below the one you’ll change:

value = “\””+value+”\””

just puts quotation marks around the value. This is necessary when you return a string as the value and that string has more than one word. If you return a list, you don’t need to add quotation marks, though you may need to add them around each string in the list.

App Inventor TinyWebDB Protocol

TinyWebDB provides two key functions: StoreValue(tag,value) and GetValue(tag) which allow an app to store and retrieve tag-value pairs. To respond to the app’s request, an App-Inventor-compliant service should handle post requests as defined below:

If the API is not providing a database storage, and just returning data, it need only respond to get_value(tag) requests, as in the sneak peak above.

Hello Tag  Sample API

You can download the Hello Tag API here:

This sample code is a bare-bones version of an App-Inventor-Compliant web service. It  responds to get_value (tag) requests with “hello tag”. The sample:

• Provides both a web page and API interface. You can test the service with the web page interface. Your App Inventor app will talk to the API interface.
• Implements only the GetValue operation, not the StoreValue. You should not call StoreValue from your app if you are using this service.

When you download the sample, you’ll see that it has the following files:

• main.py — The Python controller code, this is the meat of the API.
• index.html — The web page template for the web interface to the API.
• app.yaml — App Engine config file

• If you don’t have it, download App Engine for Python at http://code.google.com/appengine/. After installing it, run the GoogleAppEngineLauncher by clicking its icon.
• In the GoogleAppEngineLauncher, choose File | Add Existing Application. Browse to set the Path to the  folder with your code.Then click the Run button. This will launch a test web service that runs on your local machine.
• You can test the service by opening a browser and entering “localhost:8080″ as the URL. You’ll see the web page interface to your web service. The end-goal of this service is to communicate with a mobile app created with App Inventor. But the service provides a web page interface to the service to help programmers with debugging. You can invoke the get and store operations by hand, view the existing entries, and also delete individual entries
• Your app is not yet on the web, and thus not yet accessible to an App Inventor app. To get it there, you need to upload it to Google’s App Engine servers.
• In the GoogleAppEngineLauncher, choose Dashboard. Enter your Google account information and you’ll be taken to an App Engine dashboard.
• Choose Create an Application. You’ll need to specify a globally unique Application Identifier. Remember the Application identifier as you’ll need it later. Provide a name to your app and click Create Application to submit. If your Identifier was unique, you now have a new, empty app on Google’s servers.
• Open a text editor on your local computer and open the file app.yaml within your project folder. Modify the first line so that the application matches the application identifier you set at Google.
• In GoogleAppEngineLauncher, choose Deploy and follow the steps for deploying your app.
• Test to see if your app is running on the web. In a browser, enter myapp.appspot.com, only substitute your application identifier for “myapp”. The app should look the same as when you ran it on the local test server. Only now, it’s on the web and you can access it from your App Inventor for Android app.

App Inventor Client Apps

Once you have an “App-Inventor-compliant” web service, you can create App Inventor apps that access it. For the sample you just created, do the following:

• Drag in a TinyWebDB component into the Component Designer.
• Modify the ServiceURL property from the default (http://appinvtinywebdb.appspot.com/) to the URL of your service.
• In the blocks editor, call TinyWebDB.getValue with a key appropriate to your service.

Here is how the blocks look for a call to the sample API:

The app get the user’s input from TagTextBox and sends it as the tag in the TinyWebDB’s GetValue call. This triggers an API get_value request. The API returns the value (hello:tag) to the phone. When the data arrives, the TinyWebDB.GotValue event is triggered and the app just displays the value in the ValueLabel.