You may work alone or with a partner of your choosing.
Goal
- Learn to use the Flask web framework to implement
HTTP-based APIs in Python.
Rubric
1 - author names in comment at top of olympics-api.py
1 - olympics.sql loads properly via "psql olympics < olympics.sql"
2 - olympics-api.py runs and responds to queries from a browser
1 - /games endpoint is correct
1 - /nocs endpoint is correct
1 - /medalists/games/<games_id> endpoint is correct with
no GET parameter
1 - /medalists/games/<games_id> endpoint is correct with
the noc GET parameter
4 - code organization and quality
An Olympics data API
For this assignment, you will implement an API based on the
Olympics database you designed and populated last week.
Soon, you'll be implementing an API of your own design, but this time,
I'll give you the API design up-front so you can focus your attention on implementation only.
As you think about APIs, it's important to remember that the client of an API is another
piece of software, not a human being. So a well-designed API needs to consider the likely
needs and convenience of other software (which in turn may be serving human beings directly). For example,
for a dynamic website based on our Olympics data, the browser might want to populate
an alphabetized drop-down list of all the cities that have hosted Olympic games. To serve that
sort of need, it would make sense to provide a /cities API endpoint, which would give the client
a convenient (and maybe pre-sorted) list of cities in JSON form, like: ["Athens", "Barcelona",...].
The API described here is a small fragment of the API I would design if I wanted to
create a feature-rich online resource about the Olympics. But our purposes are just to get you some
practice implementing APIs, so the endpoints described below should do that job.
Here are the API endpoints you'll implement:
REQUEST: /games
RESPONSE: a JSON list of dictionaries, each of which represents one
Olympic games, sorted by year. Each dictionary in this list will have
the following fields.
id -- (INTEGER) a unique identifier for the games in question
year -- (INTEGER) the 4-digit year in which the games were held (e.g. 1992)
season -- (TEXT) the season of the games (either "Summer" or "Winter")
city -- (TEXT) the host city (e.g. "Barcelona")
REQUEST: /nocs
RESPONSE: a JSON list of dictionaries, each of which represents one
National Olympic Committee, alphabetized by NOC abbreviation. Each dictionary
in this list will have the following fields.
abbreviation -- (TEXT) the NOC's abbreviation (e.g. "USA", "MEX", "CAN", etc.)
name -- (TEXT) the NOC's full name (see the noc_regions.csv file)
REQUEST: /medalists/games/<games_id>?[noc=noc_abbreviation]
RESPONSE: a JSON list of dictionaries, each representing one athlete
who earned a medal in the specified games. Each dictionary will have the
following fields.
athlete_id -- (INTEGER) a unique identifier for the athlete
athlete_name -- (TEXT) the athlete's full name
athlete_sex -- (TEXT) the athlete's sex as specified in the database ("F" or "M")
sport -- (TEXT) the name of the sport in which the medal was earned
event -- (TEXT) the name of the event in which the medal was earned
medal -- (TEXT) the type of medal ("gold", "silver", or "bronze")
If the GET parameter noc=noc_abbreviation is present, this endpoint will return
only those medalists who were on the specified NOC's team during the specified
games.
The <games_id> is whatever string (digits or otherwise) that your database/API
uses to uniquely identify an Olympic games.
Things to do
- Don't forget the flask lab
and my Flask video. These should answer at least some of your questions.
- The lab already reminded you, but don't forget to pay attention to the
flask_sample.py in my GitHub repository.
- As noted at the top of this page, you're going to continue working
in the "olympics" directory in your repository.
- Create a Flask app olympics-api.py to implement the API described above.
Testing your implementation
Here's what the grader and I will do to try out your API implementation. You
can use this same test procedure to make sure things are working OK.
- In psql, execute "DROP DATABASE olympics;" followed by "CREATE DATABASE olympics;"
to start fresh.
- At the Unix prompt: "psql -U my_user_name olympics < olympics.sql" where olympics.sql
is the file you included in your olympics folder for the previous assignment. This
puts your database tables into the olympics database on my machine.
- At the Unix prompt in your olympics folder,
run:
python3 olympics-api.py localhost 5000
- Open a browser and test each of the API endpoints in turn. For example:
http://localhost:5000/nocs [to see all the NOCs]
http://localhost:5000/games [to see all the Games]
http://localhost:5000/medalists/games/14
[to see all the medal winners in Games #14]
http://localhost:5000/medalists/games/14?noc=CAN
[to see all the Canadian medal winners in Games #14]
Have fun!