BYU Home pageBRIGHAM YOUNG UNIVERSITY
  Office of Digital Humanities
Back     BYU LiveCode Lessons Gateway

DigHT 310
Implementing GET method APIs

There are essentially two approaches to implementing a web service in your LiveCode stack—building an interface based on a published API, or "mining" the source code of existing HTML pages. Regardless of the approach you take, once you have discovered the API, the way to implement web service access in LiveCode is identical.

Step 1: Find the API.

If there is a published API:

  1. Look up the API as described in the lesson Introduction to Web Services.

  2. Look for a sample URL string for an idea of what your final service query string will look like. For example, here's one from random.org's API:

    http://www.random.org/integers/?num=10&min=1&max=6&col=1&&base=10&format=plain&rnd=new	
  3. Most API documents will also include a table or listing of all of the possible arguments (the "name" part of the name=value pair) and all of the possible values for each argument (the "value" part of the name=value pair.)

These arguments and possible values are your guide to how to construct your LiveCode interface. Think of each possible argument as requiring its own control object, and the possible values as determining what kind of control object is required. For example, if an argument can have one of two possible values, use a group of two radio buttons. If an argument takes a user input as a value, use a text entry field. If an argument takes one of several values, use an option menu, and so forth.

If there is no published API:

Duplicating the functionality and power of a web-based form in your LiveCode stack can be surprisingly simple. Here is a step-by-step process for doing this, using as an example an online etymological dictionary, www.etymonline.com. (Yes, I know the process looks long and daunting from this end, but I opted for detail over conciseness. Just take it step by step.)

  1. Find a web site with a form whose functionality you would like to implement in LiveCode.

  2. Fill in the form on the web site and submit it.

  3. Look at the URL and copy the arguments list (arglist for short) at the end of URL. It should begin with a "?".

  4. The arglist should consist of a series of name=value pairs, separated by & symbols. Here is an example from http://www.etymonline.com/index.php, which is a site that lets you search for word origins. After submitting a query on the term "fool's gold", and choosing the Search Mode "Find exact phrase" the arglist is:

    ?search=fool%27s+gold&searchmode=phrase
    	
  5. Since there is no published list of arguments with their possible values, we have to dive into the HTML source code of the page. (Read more on how to build an arglist by reading forms in HTML source code.)

    First we have to find them all. Look at the web page's source code (most browsers have a "View Source" or "Page Source" option in the View menu.) Scan down until you find the <form> tag. It looks something like this:

      <form action="http://www.etymonline.com/index.php" method="get">
      <div id="search">
       Search:
       <input type="text" name="search" value="fool's gold" size="40" 
       maxlength="255" class="initial_focus"/>
       <select name="searchmode" size="1">
        <option value="none">Search Mode</option>
        <option value="nl">Natural Language</option>
        <option value="term">Find single term</option>
        <option value="or">Find any term</option>
        <option value="phrase" selected="selected">Find exact phrase</option>
       </select>
       <input type="submit" value="OK" />
      </div> <!-- SEARCH -->
      </form>
    

    Examine the tags inside the form. You see one that begins <input type="text". That's the text field where you type in the search term. After that you see <select name="searchmode" size="1"> followed by several lines of option tags. These lines give both the searchmode codes—the part after "value="—and the actual text that appears in the option menu, framed by the <option ..> </option> tag. We'll need both of these in our stack's "searchMode" option menu. Just copy-paste or transcribe them into two lists, being careful to match up the two lists line for line:

    searchmode codes option list visible text
    none
    nl
    term
    or
    phrase
    Search Mode
    Natural language
    Find single term
    Find any term
    Find exact phrase


Step 2: Implement the Web Service form in LiveCode.

  1. Now your whole task in your LiveCode stack is to exactly duplicate the arglist derived from the web site or published in the web service's API.
    1. First, create the form in your LiveCode stack by building the interface with all of the control objects you need. Let's follow the etymonline.com example, as it is fairly straightforward.

      Original Web search form


      The form on the web page looks like this:



    2. Now you have to write a handler in your "lookup" button that assembles the URL, submits it and then shows the results in field "definition". Remember that it is important to convert spaces and other non alphanumeric characters to a form that lets them traverse the internet safely. LiveCode gives us a function to do this, called urlEncode(). Here's how it works.

      Earlier you created an option menu called "SearchMode". You build your arglist out of the user inputs to field "searchTerm" and button "searchMode", making sure you pre-process the value portion of each name=value pair with urlEncode():

       put the menuHistory of btn "SearchMode" into tModeNum
       put line tModeNum of the searchModeValues of btn "searchMode" into tMode
       put "?search=" & URLEncode(fld "searchTerm") & \
           "&searchmode=" & URLEncode(tMode) into tArglist
       -- tArglist should be ?search=fool%27s+gold&searchmode=phrase
      
  2. Once your arglist is built, all that's left is to build your complete URL and "submit" it to the host server. Use a simple put URL statement:

    In your "lookup" button:

      put url ("http://www.etymonline.com/index.php" & tArgList) into tReturnedData
    
  3. The variable tReturnedData will most likely contain raw HTML code. That means you'll have to examine it to determine where the desired data is. The returned output will always be in the same general format, so you can safely design a strategy for parsing out what you need.

    In this example, a scan through the returned HTML output reveals a section that looks like this:

    <div id="dictionary">
    <dl>
    <dt class="highlight"><a href="/index.php?term=fool">fool (n.)</a>
    <a href="http://dictionary.reference.com/search?q=fool" class="dictionary"
    title="Look up fool at Dictionary.com"><img src="graphics/dictionary.gif" 
    width="16" height="16" alt="Look up fool at Dictionary.com" 
    title="Look up fool at Dictionary.com"/></a></dt>
    <dd class="highlight">late 13c., from O.Fr. <span class="foreign">fol</span>
    "madman, insane person," also an adj. meaning "mad, insane," from L. 
    <span class="foreign">follis</span> "bellows, leather bag," in 
    V.L. used with a sense of "windbag, empty-headed person" 
    (see <a href="/index.php?term=follicle" class="crossreference">follicle</a>). 
    Cf. also Skt. <span class="foreign">vatula-</span> "insane," 
    lit. "windy, inflated with wind."
    <blockquote>
    "The word has in mod.Eng. a much stronger sense than it had at an earlier period; 
    it has now an implication of insulting contempt which does not in the same degree 
    belong to any of its synonyms, or to the derivative <span 
    class="foreign">foolish</span>." [OED]</blockquote>
    Meaning "jester, court clown" first attested late 14c., though it is not always 
    possible to tell whether the reference is to a professional entertainer or an amusing 
    lunatic on the payroll. As the name of a kind of custard dish, it is attested from 1590s 
    (the food was also called <span class="foreign">trifle</span>, which may be 
    the source of the name). The verb meaning "to make a fool of" is recorded from 1590s. 
    Related: <span class="foreign">Fooled</span>; <span class="foreign">
    fooling</span>.
    As an adjective, <span class="foreign">fool</span> “foolish, silly” is considered 
    modern U.S. colloquial, but it is attested from early 13c. <span class="foreign">
    Feast of Fools</span> (early 14c.), from M.L. <span class="foreign">
    festum stultorum</span>) refers to the burlesque festival celebrated in some churches 
    on New Year's Day in medieval times. 
    <span class="foreign">Fool's gold</span> "iron pyrite" is from 1882. 
    <span class="foreign">Fool's paradise</span> "state of illusory happiness" is 
    from mid-15c. <span class="foreign">Fool around</span> is 1875 in the sense of 
    "pass time idly," 1970s in sense of "have sexual adventures." 
    <span class="foreign">Foolosopher</span>, a most useful insult, turns up in 
    a 1549 translation of Erasmus. <span class="foreign">Fool’s ballocks</span> 
    is described in OED as “an old name” for the green-winged orchid.</dd>
     </dl>
     </div> <!-- DICTIONARY -->
     
    

    Since the information we want is bracketed between <div id="dictionary"> and </div> <!-- DICTIONARY --> it is a simple matter to discover where these lines occur in tReturnedData and extract everything between those lines. Here's a possible approach:

        put "<div id=" & quote & "dictionary" into tStartString
        put "</div> <!-- DICTIONARY -->" into tEndString
        put lineOffset(tStartString,tReturnedData) into tStartLine
        put lineOffset(tEndString,tReturnedData) into tEndLine
        put line tStartLine to tEndLine of tReturnedData into tDefData
        set the htmlText of fld "definition" to tDefData
    
  4. All that's left now is to clean up the output so that it appears neatly in your field. That may involve replacing tags within tDefData with tags that LiveCode understands. (For example, you could replace the <span ...> </span> tags with simple <i> </i> tags.)

There is a working example of this in the webServices.rev stack that is in the InClass/webservices folder on the DigHT 310 web site.

As an exercise to help you learn how to do this, find an example of a form that uses the GET method on a web site of your choice and convert it to run in a LiveCode stack. Make it polished, the way you'd want it if you were having strangers use it. That means the output is well-formatted and readable and the interface is reliable and easy to use.


Back     BYU LiveCode Lessons Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University.
This page last updated on June 14, 2016 10:18:18.