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 cygwin, 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 I'm forgetting).
• 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 fall 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.

• Retrieve your email from Mike Tie (mtie) from March, in which you'll 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

• Login to thacker.mathcs.carleton.edu
• cd to /var/www/html/cs257/yourusername (see below)
• IGNORE THE .wsgi FILE. Mike and I changed our minds about how to handle your Flask apps.
• Create a Flask app file called api.py. At first, copy example_flask_app.py to api.py to test your setup. Edit the "app.run(host='localhost', port=5000)" line to "app.run(host='thacker.mathcs.carleton.edu', port=YOURPORT)" where YOURPORT is your port from the list below. (Use the 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. 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 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. So you may find that you'll have to wait for a bit before relaunching your api.py server. Alternatively, you could use one of your partners' ports and switch back and forth as you work.

Your port

Here's each person's port for using Flask on thacker.