Web Services Mini-exercise: Millions of Cats

Concepts taught: 
- the URL keyword in LiveCode: gives access to containers outside of LC (file:, binfile:, http:)
- result returned as JSON encoded text
- URL element in result is URL to cat image 
- converting JSON to LiveCode Array with JSONToArray function
- the filename property of LC images - images can directly display images on the web


API: https://docs.thecatapi.com/ - Go there in your browser.

What is does: Allows you to search thousands of cat images. You can get a free API Key for access to the whole API, or you can use the QuickStart.

Quickstart - Get a random Kitty
Using the language / framework of your choice:

Load https://api.thecatapi.com/v1/images/search
Get the first Array object of the JSON response
Load its URL
Enjoy the kitty 😺
Bonus: Add a button to repeat the request for a new kitty!

STEPS
1. Make stack with 
	- button "seecat"
	- field "apiurl"
	- field "apiresults"
	- image "aCat"
	
2. In button:
on mouseUp
    put fld "apiurl" into tURL
    put url tURL into tResults
    put tResults into fld "apiresults"
end mouseUp

3. Note that a result string similar to this is returned in fld "apiresults":
[{"breeds":[],"id":"GQXuSIqUv","url":"https://cdn2.thecatapi.com/images/GQXuSIqUv.jpg","width":2475,"height":3304}]
This is JSON-formatted text; specifically a JSON-formatted array.

4. Note that you can easily spot a URL string in the result. Copy this string from the field and open the property inspector for image "aCat". Paste the URL string into the filename property field (labeled "Source"). The image should appear in the image object.

5. Now we want to make an image automatically display in the image object each time we click the button--no copying and pasting! To do this, let's see if LiveCode knows what to do with a JSON string. A quick check of the Dictionary, searching on JSON shows us that there is a JSONToArray() function. That looks like it might do the trick! Add the following line to your button handler:

    put JSONToArray(fld "apiresults") into tResArray

6. Check the keys of this array in the message box, and you'll see:

	put the keys of tResArray --> 1
	
	This means that the array has one element with a key of "1" and inside that element is another array, so it's a two-dimensional array:
	
	put the keys of tResArray 
	--> breeds
		height
		id
		url
		width
		
	So to get the information we want we need to look at tResArray[1]["url"]
	
7. Now add this to the end of the button's handler:

	set the filename of image "aCat" to tResArray[1]["url"]
	
	This is a basic, functioning stack. But read on to make it a bit more user friendly.
	
THE "POLISH"
8. Each cat image has its own dimensions, and sometimes it ends up covering the entire card, and then some. Here is an expanded mouseUp handler that shows one way that you could automatically resize the image to fit on the card every time. I'll leave it to you to figure out what is going on; it's pretty straightforward:

on mouseUp
    put fld "apiurl" into tURL
    put url tURL into tResults
    put tResults into fld "apiresults"
    
    put JSONToArray(fld "apiresults") into tResArray
    set the arrayData of widget "arrayTree" to tResArray
    set the filename of image "aCat" to tResArray[1]["url"]
    
    put tResArray[1]["width"] into tImgWidth
    put tResArray[1]["height"] into tImgHeight
    put the width of this card into tAvailWidth
    put the height of this card - the bottom of fld "apiresults" into tAvailHeight
    
    # resize the image if needed
    set the resizeQuality of img "aCat" to "good"
    # first check the height to see if the native height is too much
    if tImgHeight > tAvailHeight then
        put tAvailHeight / tImgHeight into tResizeFactor
        set the width of img "aCat" to the width of img "aCat" * tResizeFactor
        set the height of img "aCat" to the height of img "aCat" * tResizeFactor
    end if
    
    # now check to see if the resized image is still too wide
    if the width of image "aCat" > tAvailWidth then
        put tAvailWidth / tImgWidth into tResizeFactor
        set the width of img "aCat" to the width of img "aCat" * tResizeFactor
        set the height of img "aCat" to the height of img "aCat" * tResizeFactor
    end if
    
    # position the image
    set the loc of image "aCat" to the loc of this cd
    set the top of image "aCat" to the bottom of fld "apiresults"
end mouseUp

See Key Stack: catApiStack.livecode

EXPLORE THIS API FURTHER

Go to the main page at https://thecatapi.com/. Sign up for an API key. Read the documentation to see if you can figure out how to do other, more specific searches on the API.