Create an 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

You’ll download some sample code below. Its some HTML and Python code that can be deployed on Google’s cloud using App Engine. But to show you how easy it is to create an App-Inventor-compliant API, let’s take a look at the code you’ll actually need to look at and change. The customizable part is in the file main.py and specifically  in the GetValueHandler.get_value function:

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:

TinyWebDB Client Call API Request
StoreValue(tag,value) store_value(tag,value)
GetValue(tag) get_value(tag)

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
Once you’ve added your custom code, you can test and deploy the service following these instructions:
  • 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.

6 Responses

  1. Nice explanation

  2. Hello, I have this spreadsheet http://cid-5054dd243c01e71b.office.live.com/view.aspx/.Documents/Livro1.xlsx on the web.

    if I input two values (example TexBox1 = 15 and TexBox2 = 0,817) in my app
    I would like to verify the spreadsheet above
    and return the value 0,8135
    because I found 15 – TexBox1 in the Column 1, Row 9
    and I found 0,817- TexBox2 – in the Column 9, Row 1

    So I would like to have the value in the Cell(9,9) from the spreadsheet which is 0,8135

    Could I use TinyWebDB to get 0,8135 in the TexBox3 ?
    How could be possible?
    I appreciate any help about this issue.

    Many thanks for you guys,

    Flavio

  3. Hello Guys,
    I can’t seem to find a definite answer to this. If I make a custom database, does the 1000 entries limit still apply? Is there a large limit or do you need to pay for more entries?

    • Hi Mark. I don’t believe the 1000 entry limit is part of any of the samples. If it is, it is due to a simple if statement in the code (main.py), and you can remove it. It is not an app engine limit.

      Limits on app engine can come from data or #hits, but I believe data limit will be much higher than 1000 entries before you need to start billing.

      Dave

  4. Thanks Dave, at least I know I can use the service without hitting a roadblock soon!

    Thanks again for the help!

    Mark

  5. Hi, can i know if the ‘values’ stored in this app inventor’s tinyWebDB is only possibly by user input? Meaning in the app user types something and it is saved to tinyWebDB.
    OR
    is it possible to store values that are not user-generated? Meaning the ‘values’/data is sent from an arduino via bluetooth to the phone app and then the app saved these values to tinyWebDB.

    Pls do reply soon! Im hitting a wall right now because the data i need to store are not user-generated/input but from an arduino. thank you very much

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 59 other followers