Web Services Mini-exercise: A Random Random API

Concepts taught:
- REST architecture
- GET method
- Constructing a URL with argument string
	- LiveCode's URLencode() function
	
	
API: https://www.random.org/

What it does: Presents information about a number of APIs that generate random... stuff. Numbers, sequences of numbers, simulated coin flips, etc.

We're going to try one of their APIs out using the "URL hacking" technique that we used with Google search. Only this time we're going to set up a form in our LiveCode stack to query the API and display the result. This is a really simple API to use because it has the option of returning the result as either plain text or HTML.

STEPS
1. Go to the website random.org. 

2. From the home page click on Integer Generator under the Numbers section.

3. Notice the simple form on that page. It lets you choose:
• how many random integers to generate, 
• the range of values for each integer, 
• and how many columns the result should be.
Then there are "Get Numbers" and "Reset Form" buttons. We'll ignore the Switch to Advanced Mode button for now.

4. Fill in the fields and click Get Numbers. Observe the result. 

5. Now look at the browser's URL field at the top of the window. It will show a URL "GET" request string that looks something like this:

https://www.random.org/integers/?num=10&min=1&max=100&col=3&base=10&format=plain&rnd=new

6. Focus on the part of the URL string beginning with "?". That is what is called an argument list. It is composed of name=value pairs. We are going to use a LiveCode stack to duplicate this request string and get the result back.

7. Make a card in a stack with these controls. (Obviously you can name them whatever you want.) 
	- field "numIntegers"
	- field "low"
	- field "high"
	- field "numColumns"
	- button "submit"
	- field "results"
	
8. We will construct the argument list by plugging the values from the fields into the name=value pairs.

9. In the "submit" button, first grab all of the values from the fields and the group:

on mouseUp
    put fld "numIntegers" into tNum
    put fld "low" into tLo
    put fld "high" into tHi
    put fld "columns" into tCol
    put the hilitedButtonName of group "styleGrp" into tStyle

end mouseUp

10. Now create the argument list of name=value pairs and concatenate it onto the end of the base URL. Add these lines to your mouseUp handler:

	put "?num=" & tNum & "&min=" & tLo & "&max=" & tHi & "&col=" & tCol & "&base=10&format=plain&rnd=new" into tArgs
	put "https://www.random.org/integers/" & tArgs into tURLstring
	put URL tURLstring into fld "results"
	
11. Test your form by filling in all of the fields and clicking the submit button. 

See Key Stack: randomAPI.livecode

EXPLORE THIS API FURTHER

Go back to the home page random.org. Under the Web Tools and Widgets for Pages, click HTTP API to see the complete documentation for the Integer Generator and other random generators. Can you figure out how to access any of the other generators, or how to enhance the Integer Generator we just made? For instance, how could you choose to display your random numbers in base 2 or base 16?