API design

You will work with your web application team for this assignment.

Goals

Prepare a first draft design for the API that will provide the data your web application needs.
Practice using a few simple API design principles.

Rubric

1 - files and names in the right places 4 - documentation is clear and follows the requested format 3 - collection of endpoints is appropriate for your dataset

Where the API fits in your overall project

For this project, we will use an organization in which sometimes the user's browser asks your application for pages for the user to view, and sometimes the user's browser asks your API for data, which gets incorporated into the browser display.

How all this works is coming up over the next few weeks. But for now, we want to focus our attention on the data you have chosen for your project.

What questions will your application and its user want to ask of your dataset?
How can those questions be articulated in the form of API endpoints?

Some example endpoints

Example 1: Olympic sports

Suppose I want to populate a drop-down list with the alphabetized list of Olympic sports. Then I might want my API to include an endpoint like this:

REQUEST: /sports RESPONSE: an alphabetized JSON list of strings, each of which is an Olympic sport.

(By the way, using an API endpoint to populate a drop-down list is preferable to hard-coding the list of sports in a web page, because the application would adapt automatically if the 2026 winter games added a new sport, like "Below-Freezing Flagpole-Licking".)

Example 2: books and authors

Suppose my application includes a Search button to let me search for all the books whose titles contain my search string. Then my browser may want to ask my API a question like this:

REQUEST: /books/title_contains/{search_text}

or, depending on your preference and your other endpoints:

REQUEST: /books?title_contains={search_text}

Either way, you will want to describe the API response format like so:

RESPONSE: a JSON list of dictionaries, each of which represents one book, sorted by publication date. Each book dictionary will have the following fields. title -- (string) the title of the book author -- (string) the full name(s) of the author(s), semicolon-delimited if there is more than one author publication_year -- (int) the year the book was published

Here's another example endpoint for this dataset with a more thorough demonstration of the documentation style I would like you to use. (The pros use web-based documentation like Swagger/APIHub or PortSwigger, but for now, let's try to keep the number of new tools for you to learn capped at "about a million" instead of "about a billion".)

REQUEST: /authors GET parameters search_text (Optional, default: '') -- return only authors whose first or last names contain search_text, case-insensitively start_year (Optional, default: -infinity) -- return only authors who were born no earlier than start_year end_year (Optional, default: infinity) -- return only authors who died no later than end_year RESPONSE: a JSON list of dictionaries, each of which represents one author, sorted alphabetically by last name (and sorted alphabetically by first name when last names are equal). Each dictionary in this list will have the following fields. last_name -- (TEXT) the author's last or family name first_name -- (TEXT) the author's first or given name or names birth_year -- (INTEGER) the year the author was born death_year -- (INTEGER) the year the author died (or 'NULL' if still alive) EXAMPLE: /authors?search_text=bront&start_year=1817 [{"last_name":"Brontë", "first_name":"Ann", "birth_year":1820, "death_year":1849}, {"last_name":"Brontë", "first_name":"Emily", "birth_year":1818, "death_year":1848}] (no Charlotte, since she was born in 1816)

Of course, this API would have many different endpoints, not just /books.

Your tasks

For this assignment you're going to decide, based on your user stories and wireframes, what endpoints your API will probably require. You'll then document those endpoints.

More specifically, create a file called api-design.txt in your doc directory. This file should contain:

Your names
Documentation for a list of API endpoints. Use REQUEST and RESPONSE descriptions like those above. Shoot for the neighborhood of 2-5 endpoints, depending on the nature of your dataset.

By the way...

If we were a startup and I were your manager, at this stage of the project I would also require you to write a suite of unit tests for the API. For this project, I am not going to require unit tests yet, but we'll get there.