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.
bakerk2 5102
bursonj 5103
celikk 5104
chavezl 5105
chenx2 5106
childv 5107
considinez 5108
crenshawm 5109
cristofaroe 5110
dewans 5111
domogallaj 5112
donahuec2 5113
forbesd 5114
greenm2 5115
greenbergh 5116
hallstromr 5117
hedayatim 5118
javalym 5119
kapelkei 5120
kimj4 5121
kleina3 5122
kleina2 5123
konuka 5124
kuob 5125
lacroixa 5126
liur3 5127
liut2 5128
mawbye 5129
mchughs 5130
neubauers 5131
orvisw 5132
phillipsl 5133
pitkofskyj 5134
richardsw 5135
rosenberge 5136
serranos 5137
shenr 5138
shoemakerc 5139
spinalen 5140
tagoec 5141
taod 5142
tigara 5143
villarrealm 5144
wangs3 5145
wangy2 5146
warrena 5147
wooldridgep 5148
woosnama 5149
jondich 5150