CS 257: Software Design

Lab: getting started with Flask

Flask: a web framework

Once you have designed your HTTP-based API, you'll want to write code to implement it, and deploy that code on a publicly accessible server.

One of the biggest hassles of API implementation is the parsing of the URL. For example, if you're implementing queries like "http://wherever.com/author/27", you'll need code to recognize that the caller is requesting the "authors" resource with the author id 27. Once this information is extracted, you'll probably want to call some sort of get_author function with the parameter author_id=27, after which get_author can then do the job of querying the database and assembling the JSON response to be sent back to the browser/client.

In addition to URL parsing, there are other routine and tedious tasks involved in implementing web services. As a result, many people have devloped "web frameworks"—tools to simplify some of these routine tasks. We will be using one such framework called Flask, one of the most popular Python web frameworks. You can run Flask directly on perlman.mathcs.carleton.edu, or you can install it on your own machine. Using Flask will enable you to focus your attention on the core algorithmic content of your API instead of on repetitive details like URL parsing.

Using Flask on perlman, Part 1: Moving files

There are many ways to move files from computer to computer over the internet. Here are a few ways to get your files to perlman.

• You can use SCP (Secure Copy). On your own machine, cd to wherever the files are. Then:
  scp file_to_transfer YOURUSERNAME@perlman.mathcs.carleton.edu:/var/www/html/cs257/YOURUSERNAME
  or if you want to transfer a whole directory:
  scp -r dir_to_transfer YOURUSERNAME@perlman.mathcs.carleton.edu:/var/www/html/cs257/YOURUSERNAME
• You can use SFTP (Secure File Transfer Protocol). First, on your own machine, cd to wherever the files are. Then execute "sftp YOURUSERNAME@perlman.mathcs.carleton.edu". You'll get an sftp prompt. At that prompt, you can execute some basic Unix commands, like ls. So cd to your desired destination directory, and then "put FILE_YOU_WANT_TO_TRANSFER". Repeat as needed for all files.
• If your desired files are in a git repository, you can login to perlman, cd to /var/www/html/cs257/YOURUSERNAME, and then execute "git clone URL_FOR_GIT_REPO".
• Get a GUI client for SFTP or SCP for your computer. Tons of them are available. Search for "gui sftp mac" or "gui sftp windows" or something like that to get suggestions.

Using Flask on perlman, Part 2: executing Flask apps

• Login to perlman.mathcs.carleton.edu
• cd /var/www/html/cs257/YOURUSERNAME
  (by the way, that path is a soft link pointing to /Accounts/courses/cs257/jondich/web-f2018/YOURUSERNAME, so you can cd to either one)
• Copy flask_sample.py to this directory. Rename the program api.py (this renaming is just to emphasize to you that this Python program is an implementation of a very simple API).
• Read the flask_sample.py code. Note the hard-coded "database" at the beginning, and then read the code and comments at the "app.route" lines. This should give you an idea of what URLs are legal for this API (these legal URLs are also known as the endpoints of the API).
• Get the ports assigned to you by Mike Tie by checking the email he sent you in August or this list (which is missing a couple people who added the class later).
• Run api.py by just typing "api.py". (Permission denied? Remember the discussion of file permissions and chmod from class a couple weeks ago? You might want to do "chmod +x api.py" to allow you to execute api.py directly.) When api.py runs, you'll get a Usage statement.
• Try it again:
  api.py perlman.mathcs.carleton.edu YOURPORT
  Once api.py really launches, you'll get a status message, including a URL you can run to access the API.
• Use a browser to go to http://perlman.mathcs.carleton.edu:YOURPORT/ to see whether your setup is right. (You have to be coming from a Carleton IP address for this to work. If you're off campus at the time, you can use the Carleton VPN to put your computer on the Carleton network.)
• Take a look at the terminal window where you launched api.py. Do you see any log messages? Try reloading the page in your browser and see if you get more logging in the terminal.
• Read the api.py code and play around with possible API endpoints/routes to make sure you understand which code is getting called, and when.
• Hit Ctrl-C in your terminal (it might take three or four times) to stop api.py.
• Next, we'll launch api.py "in the background":
  api.py perlman.mathcs.carleton.edu YOURPORT &
  That is, exactly as before, but with an ampersand at the end. This causes api.py to execute, but it also gives you the bash prompt back. Go to your browser and try one of the URLs you've been using for testing. It should still work as before.
• Logout of perlman. Try another URL. Does api.py still respond?
• Log back in to perlman. Is api.py still running? Here's one way to see:
  ps auxww | grep api.py
  That lists all the running processes whos commands include the string "api.py". You should see a couple such processes.
• Let's shut down api.py. In the ps display you just looked at, the <=5-digit number in the second column is known as the process ID. To shut down your api.py, get its process ID from ps and then execute the command:
  kill PROCESS_ID
  After you do that, try the ps/grep thing again to see whether the api.py processes are indeed gone.
• Sometimes when you kill a process that is listening on a port, that port remains unavailable for reuse for a few minutes. That's one reason why Mike gave you two ports: so you can switch back and forth as you work if you need to.

So where are we?

At this point, you can launch a simple Flask web app on perlman and access it via a browser.

Next, you'll want to start implementing your API. To do that, you'll use the functions in flask_sample.py to give you an idea of how to build additional "@app.route" endpoints corresponding to the API you designed in phase 3. You might also find the official Flask documentation helpful.

Here's one approach:

• Pick one endpoint from your API design (e.g. "/author/<author_id>").
• Create a stub function in api.py that matches the endpoint:
  @app.route('/author/<author_id>') def get_author(author_id): author = {'id': author_id, 'first_name': 'Alice', 'last_name': 'Stubauthor', 'birth_year': 1900, 'death_year': 1980} return json.dumps(author)
• Fire up api.py and test the new endpoint (e.g. try different values of author_id and see if you see the difference in the JSON shown in your browser).
• (Maybe commit and push to your feature branch, just to save the endpoint stub.)
• Do the hard work: implement and test your API endpoint.
• Repeat

Alternatively, you could create all the endpoint stubs at once, test that they are getting called at the appropriate times, and then start implementing them one at a time.

[Optional] Using Flask on your own computer

Having Flask working on your own machine can help make development of your API more convenient than using the CS department server.

• Find out whether your python3 installation includes "pip3", the standard Python package/module installer. In bash, execute "which pip3" to find out (if there's no response from which, then pip3 is not installed in any of the places your PATH environment variable points to, so it's probably not installed at all).
• If not, the best solution is to make sure your python3 version is 3.4 or higher, because pip3 is installed automatically. Check your version with "python3 --version".
• Install flask: "pip3 install flask". This will also install some other packages (werzkreug, jinja2, maybe some other stuff).
• Save flask_sample.py in a convenient working directory on your computer.
• Do the chmod thing and get flask_sample.py (renamed api.py) running on your computer as we did on perlman above. But now, you'll use "localhost" as your host, and something conventional (e.g. 8080) as your port:
  api.py localhost 8080
• Test it in a browser: http://localhost:8080/actor/adams
• Ctrl-C, ampersand, ps auxww | grep api.py, killall, etc. work just as they do on perlman. I generally don't do the ampersand/background thing on my own machine while developing the API, though.