CS 257: Software Design

Implementing an API

Folder: olympics-api

Tag: olympics-api

Goal

Rubric

1 - author names in comment at top of olympics-api.py 2 - olympics-api.py runs and responds to queries from a browser 2 - /games endpoint is correct 2 - /nocs endpoint is correct 2 - /medalists/games/<games_id> endpoint is correct with no GET parameter 2 - /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. In a few weeks, 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.

Things to do

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.

Have fun!