CS 257: Software Design

Web Application: API design

Folder: webapp/doc

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

Goals

• Prepare a first draft of the API your web application will need to consult to obtain the data your application needs.
• Start understanding the system architecture I'm asking you to use for the web application.

Our web application architecture

Any page of your web application will consist of HTML code, which (among other things) uses a <link> tag to load a CSS file (pretend it's called mywebapp.css) and a <script> tag to load a Javascript file (mywebapp.js). This means that if a person has navigated to your page in a browser, the browser will also have retrieved webapp.css (using it to display the page) and webapp.js (parsing it and executing any of its code that needs to be executed right away).

With those assumptions, this is how a typical interaction with your web application will go.

• The person has loaded into a browser your home page, which includes a search box and a Submit button. (You might not have these two things on your home page, but for the sake of concreteness in this discussion, let's pretend you do.)
• The person types "Pangolin" into the search box and clicks the Submit button.
• The click triggers a Javascript function in webapp.js (let's call it onSubmit).
• onSubmit sends a query to one of your API endpoints (whichever one is relevant), asking it to do a search for the string "Pangolin". At the same time, onSubmit specifies some code (let's say it's a function called onSearchResults) to be called when the API response arrives.
• Your API endpoint translates the API query into a SQL query and sends it to PostgreSQL on your server.
• PostgreSQL does the query and returns the results to your API as database rows.
• Your API endpoint accesses these rows using a psycopg2 cursor object, and transforms them into JSON.
• Your API endpoint function returns the JSON, which causes the Flask code to send the JSON back to the browser.
• The Javascript function onSearchResults, running in the person's browser, turns the JSON into Javascript dictionaries, lists, etc. as appropriate, and then uses that data to change the HTML of the page (presumably to show a table or a graph or something to show the search results).
• The browser updates the display to reflect the new HTML.
• The person is happy.

More concisely, the queries and responses flow like this: person clicking → Javascript → API server → database → API server → Javascript → browser display → user

I'll talk another time about how this wouldn't have to be our architecture, and what pedagogical and engineering motivations I have for choosing it.

How do we put that all together?

We'll need to implement as many of these pieces independently as possible. This is one of the hardest parts of complex projects—how to put sequence the work so that you can focus your attention on one small part at a time, and test those small parts independently of the system as a whole.

For the moment, I want you to focus on the part of the story where onSubmit asks the API for the data it needs, and onSearchResults takes the JSON that comes back from the server and turns it into HTML. These two interactions will give you insight into what kind of endpoints your API is going to need.

Suppose, for example, that the Submit button lets me search for all the books whose titles contain my search string. Then onSubmit will probably want an API endpoint that looks something like this:

or, depending on your preference and your other endpoints:

Either way, onSearchResults (or probably onBookTitleSearchResults in this context) will want the response from the endpoint to look like this:

Or maybe you'll want the "author" field's value to be a list of dictionaries itself, each representing one author. This is a design question whose answer depends on what you want to do with the response, and whether you anticipate ever reusing this API for different purposes.

For this assignment, you're going to decide, based on your evolving user stories and wireframes, what endpoints your API will require. Just as with the database designs last week, we will do a review session during the second discussion group meeting this coming week. (Though Mooses, this assumes we'll be able to get past talking about the election Wednesday morning.)

Your tasks

Create a file called api-design.txt in your webapp/doc directory. It should contain:

• Your names
• A list of REQUEST and RESPONSE descriptions like the above for each of the endpoints you expect your API to need.

Start early, ask questions, and have fun!