CS 257: Software Design

Getting Started With Flask

Throughout the following discussion, I'm going to assume you're working with Python 3. Most of the instructions work just as well with Python 2, but I won't make any special effort towards Python 2 compatibility.

Whenever I say "yourusername" below, replace it with (can you guess?) your user name.

Web API construction frameworks

Once you have designed a web 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 of parsing of the URL. For example, if you're implementing queries like "http://wherever.com/authors/Garcia+Marquez", you'll need code to recognize that the caller is requesting the "authors" resource with the author name "Garcia Marquez". Once this information is extracted, you'll probably want to call some sort of get_authors method with the parameter name="Garcia Marquez"--get_authors 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. Once you have Flask installed and configured, you can focus your attention on the core algorithmic content of your API instead of on repetitive details like URL parsing.

Of course, one of the costs of using extra tools is that you have to install and configure them. That cost is sometimes worth it, and sometimes not, depending on the tool and your needs. The rest of this document is devoted to helping you through the process of setting up and using Flask both on your own computer and on the CS department's computer thacker.mathcs.carleton.edu.

Using Flask on your own computer

Having Flask working on your own machine will help make development of your API more convenient than using the CS department server. Once you have your API working, you'll be able to deploy it to thacker.mathcs.carleton.edu so other people can see your work.

Here's how to get going with Flask on your computer.

• Find out whether your python3 installation includes "pip3", the standard Python package/module installer. On Mac or Windows bash, you can execute "which pip3" to find out.
• 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 this example_flask_app.py in a convenient working directory on your computer. Read through it.
• Run the example: "python3 example_flask_app.py". (Alternatively, make example_flask_app.py executable via "chmod +x example_flask_app.py", and then run it directly via "./example_flask_app.py".) The example_flask_app.py is now acting like a web server on your computer.
• Read the message example_flask_app.py provides for you on launch. Note that it gives you a URL to use to access the app. Try that URL in a browser. Then try a different URL (what should it be?) in the browser to cause the app to run its get_author function.
• In terminal, hit Ctrl-C (you may have to do it three or four times) to quit example_flask_app.py. Try restarting it. You may receive an error message about some port or address being "still in use" or something like that. This message will go away if you wait long enough, but you have an option in the meantime. You can change the port example_flask_app.py wants to listen on. Check the code for where that change need to be made.
• Try editing the code in one of the @app.route-marked functions, or try creating one of your own. Play around with it. Check the flask documentation. Just try some stuff to get comfortable with the example app and the development process.
• Speaking of the development process, it goes like this: change example_flask_app.py; launch example_flask_app.py; try the URLs that include the changes; quit example_flask_app.py; repeat.

Using PostgreSQL on thacker

• Login to thacker.mathcs.carleton.edu. That is, "ssh yourusername@thacker.mathcs.carleton.edu". ssh is the standard "secure shell" command that is very widely used to login to a remote machine.

  The first time you ssh into a new machine, you'll be asked whether you recognize a particular public key. Ideally, you would find out independently what the public key is supposed to be (e.g. by asking Mike Tie) before saying yes, but in practice, most people just type yes and get on with their business. Take CS231 next winter to learn more about what bad things could happen as a result. And in the meantime, you might find it handy to know that the key in question should end in "/3wRQ==".

  After that question (which should only happen the first time you login to thacker from any given machine), you'll be asked for your password. This should be your normal Carleton password.

• You should have received an email from Mike Tie (mtie) a couple days before spring term, in which you can find your postgresql password and instructions. You should be able to just run "psql yourusername" to get started in the database named "yourusername". If you're asked for a password, this time it's the one from Mike's email.

Using Flask on thacker, 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 thacker.

• If your desired files are in a git repository, you can login to thacker, cd to /var/www/html/cs257/yourusername, and then execute "git clone URL_FOR_GIT_REPO".
• You can use SFTP (Secure File Transfer Protocol). First, on your own machine, cd to wherever the files are. Then execute "sftp yourusername@thacker.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.
• You can use SCP (Secure Copy). On your own machine, cd to wherever the files are. Then:
  scp file_to_transfer yourusername@thacker.mathcs.carleton.edu:/var/www/html/cs257/yourusername
  or if you want to transfer a whole directory:
  scp -r dir_to_transfer yourusername@thacker.mathcs.carleton.edu:/var/www/html/cs257/yourusername
• Get a GUI SFTP or SCP client 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 thacker, Part 2: Executing flask apps

• Login to thacker.mathcs.carleton.edu
• cd to /var/www/html/cs257/yourusername (see below)
• Create a Flask app file called api.py. You can copy example_flask_app.py to api.py to test your setup, or you can use your own previously developed flask app. Edit the "app.run(host='localhost', port=5000, debug=True)" line to
  app.run(host='thacker.mathcs.carleton.edu', port=YOURPORT, debug=True)
  where YOURPORT is one of your ports from the list below. (Use a port associated with whichever partner's account you're working in at the time.)
• Launch your app like so: "python3 api.py &". This will launch your app as a tiny web server available at your port. The ampersand (&) will cause your app to run in the background until you kill it or thacker reboots. You'll see the associated process ID printed on the terminal just before you get the prompt back again.
• Use a browser to go to http://thacker.mathcs.carleton.edu:YOURPORT/authors/Twain or some other API call suitable to your code to see if your setup is right. Note that 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.
• Assuming all is well, you can do a couple things now. You can just logoff thacker, and your server will continue running in the background, waiting for browsers to send it queries. Alternatively, if you want to shut your server down so you can make changes to it, you can execute "kill PROCESSID" where PROCESSID is the process ID you saw when you launched api.py in the first place.
• Sometimes when you kill a process that is listening on a port, that port remains unavailable for reuse for a few minutes. That's why Mike gave you two ports, so you can switch back and forth as you work if you need to.

Your port

Here are each person's ports for using Flask on thacker.