Goals
Create a functional first draft of your web application's:
- navigational structure
- overall appearance
- most important search and display features
Your classmates will provide feedback on this draft, which should
help you polish your final submission.
Rubric
1 readme.txt lists the features that are working, and those that are not
1 - data.sql loads into an empty database without error
1 - the app runs, and has an /api/help endpoint (see below)
2 - the API endpoints respond as described in the /api/help output
2 - the / endpoint takes a browser to your home page
5 - evidence of a good-faith effort to produce a functional first
draft with core functionality working; users can search for something
and get intelligible results; navigation makes sense; etc. (see below)
Note that "code quality" is not in this rubric. The grader won't look at your code
unless the app fails to function. However, in the code review involving this first
draft, your classmates and I will absolutely look at your code, so you might as well think
about code quality now anyway, since it will receive a bunch of rubric points on the
final submission. (Also, because you have pride in your work.)
Your tasks
- Get your web application working well enough that people can try it out
enough to give you usability feedback. At minimum, I want to see:
- A /api/help endpoint that returns, as straight text (i.e. not HTML)
documentation for all your implemented API endpoints.
See below for an example of the format
I prefer.
- Pretty much complete navigation
- Good-looking styling on all pages
- Essential search functionality working. For example, if your project
is about TV shows, I want to be able to search for TV shows by title, or
if your project is about international cheese production, I'll want
to see your world map with countries colored by tons of cheese produced
in a user-specified year.
Since we're going to do a code review session to get you some detailed feedback
on this draft, the more you can have ready, the more valuable feedback
you'll get.
- Dump your database into webapp/data.sql:
pg_dump --no-owner --no-privileges -U YOURUSERNAME YOURDATABASE > data.sql
This will, of course, overwrite your previous data.sql from the end-to-end assignment. No problem.
NOTE: If your data.sql file is larger than 25MB, then don't add it to your repository.
Instead, DM it to me via Slack.
- Tag your repository webapp-draft.
- Include a text file named webapp/readme.txt, structured like this:
AUTHORS: [your names]
DATA: [a one-sentence description of your data]
FEATURES CURRENTLY WORKING:
- [very]
- [short]
- [feature]
- [descriptions]
FEATURES NOT YET WORKING:
- [same]
How we will test this draft
You can replicate the following steps to ensure that everything will work for
me, the grader, and your classmates.
- Clone your repository
- cd YOUR-REPO/webapp
- git checkout webapp-draft
- Skim your readme.txt
- psql -U jondich webapp < data.sql
- Create (or edit, if you have one in your repo, which you shouldn't)
config.py to correspond to my user name and my "webapp" database name
- python3 app.py localhost 5000
- Go to http://localhost:5000/api/help to see your endpoint documentation
- Try out a couple of your endpoints
- Go to http://localhost:5000/ and play with your site
- Test everything in a browser, taking notes for the code review
Sample API documentation
Suppose I'm doing a books/authors API. I like to have documentation with
REQUEST (including GET parameters), RESPONSE, and EXAMPLES. Like this.
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(S):
/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)
Have fun!