API Guide¶
Updated 2018-04-11.
Run the API: python3 app.py
All files must be in the same directory.
Reset the database: rm data.db
The API will run on http://127.0.0.1:5000/some_endpoint. Each time the API
runs, it will generate a new data.db.
1. Adding Books to the Database¶
To add a book to the database, send a POST request to:
/book/isbn_of_book
The body of the request should be the JSON body return from a Node.ISBN query. All JSON parsing of the body will happen on the back end.
2. Adding a User to the Database¶
To add a user to the database, send a POST request to:
/user/google_token_of_user
The body of the request should look like this:
{
"imageURL": "http://hello.com",
"name": "Big Will",
"email": "ashleygw@whitman.edu",
"givenName": "Thick Ricky",
"familyName": "Slick Nicky"
}
3. Adding a Listing to the Database¶
To add a listing to the database, send a POST request to:
/listing/isbn_of_book
The body of the request should look like this:
{
"price": 27.99,
"condition": "good",
"google_tok": "1A",
"status": "selling"
}
google_tok must be the Google token of the user making the listing. At the
moment, the only condition s that I expect are "new", "good",
"ehh", and "bad" so that Python string comparisons can uphold that
order (In this case, we are using first-character comparison.). For the MVP,
status should always be "selling". Price must be a float, not a
string. If google_tok does not match a user in the database, or if the
isbn in the endpoint does not match a book in the database, the request
will fail.
4. User -> Listing -> Book¶
This series of steps will be executed when a user wants to see their own listings on their user profile.
First, a GET request is sent to:
/book/google_token_of_user
The body will look like this:
{
"givenName": "Thick Ricky",
"familyName": "Slick Nicky",
"name": "Big Will",
"listings": [
1,
2
],
"google_tok": "1A",
"email": "ashleygw@whitman.edu",
"imageURL": "http://hello.com"
}
listings is a list of all listing_id s that correspond to each of the
user’s listings. The other information can be used to load the user’s profile,
including the image tied to their Google account, name, email address, etc.
Second, use listings to make the following GET request:
/listing/listing_ids,separated,by,commas
The response will look like this:
{
"listings": [
{
"status": "selling",
"listing_id": 1,
"timestamp": "2018-04-16 19:57:26.674665",
"condition": "ehh",
"price": 24.99
},
{
"status": "selling",
"listing_id": 2,
"timestamp": "2018-04-16 19:57:35.568820",
"condition": "good",
"price": 27.99
}
],
"isbns": [
1
]
}
listings is all of the listings tied to the user. isbns is the list of
ISBNs corresponding to the books paired with these listings. Notice that, in
this case, both listings are for the same book, which has an isbn of 1.
Use the listings data to edit the user’s home page.
Third, use isbns for the following GET request:
/book/isbns,seperated,by,commas
The response will look like this:
{
"books": [
{
"subtitle": "The Musical",
"listing_ids": [
1,
2
],
"canonicalVolumeLink": "TRIPLElol",
"title": "Moby Dick",
"isbn": 1,
"thumbnail": "http://blahBLAHblah",
"smallThumbnail": "http://blahblah",
"authors": "Will Smith, Edgar Wright",
"publishedDate": "1975",
"categories": "Artificial Intelligence, Computer Science",
"infoLink": "doublelol",
"previewLink": "lolwhatisthis"
}
]
}
This information will be used to construct the book objects. Notice that
users, listings, and books will need to be matched thorugh listing_id.
This will be cumbersome for the front end, but, hopefully, it will be more
streamlined in the final product.
5. Book -> Listing -> User¶
This pipeline will be used when a user is looking to buy a used textbook from our site.
First, the user will search by author, title, subtitle, category, or date published. The response the user types into the search bar will be used in a GET request to the following endpoint.
Important: The user’s search query must have spaces replaced by underscores (“_”) and must be converted to all lower case before being sent to the back end through the endpoint:
/booklist/search_value
The response will look like this (for /booklist/will_smith):
{
"books": [
{
"subtitle": "The Musical",
"listing_ids": [
1,
2
],
"canonicalVolumeLink": "TRIPLElol",
"title": "Moby Dick",
"isbn": 1,
"thumbnail": "http://blahBLAHblah",
"smallThumbnail": "http:://blahblah",
"authors": "Will Smith, Edgar Wright",
"publishedDate": "1975",
"categories": "Artificial Intelligence, Computer Science",
"infoLink": "doublelol",
"previewLink": "lolwhatisthis"
}
]
}
This data can be used to construct the book objects.
Second, use listing_id s to perform the following GET request.
Important: This is where condition and price ordering comes into play. To retrieve listings without any ordering:
/listings/listing,ids,separated,by,commas+
To retrieve listings ordering by lowest -> highest price:
/listings/listing,ids,separated,by,commas+price
To retrieve listings ordering by best -> worst condition:
/listings/listing,ids,separated,by,commas+condition
The response will look like this:
{
"listings": [
{
"condition": "ehh",
"status": "selling",
"listing_id": 1,
"google_tok": "1A",
"price": 24.99,
"timestamp": "2018-04-16 19:57:26.674665"
},
{
"condition": "good",
"status": "selling",
"listing_id": 2,
"google_tok": "1A",
"price": 27.99,
"timestamp": "2018-04-16 19:57:35.568820"
}
],
"google_tokens": [
"1A"
]
}
Use this data to construct the listing objects.
Third, use google_tokens for a GET request to the following endpoint:
/userlist/google,tokens,separated,by,commas
The response will look like this:
{
"users": [
{
"name": "Big Will",
"listing_ids": [
1,
2
],
"givenName": "Thick Ricky",
"google_tok": "1A",
"imageURL": "http://hello.com",
"familyName": "Slick Nicky",
"email": "ashleygw@whitman.edu"
}
]
}
Again, the listing_id will be used to match books to listings to users.
6. Loading the Home Page¶
When a user first enters Whitman Books Online, they enter a home page with listings ordered from most to least recent. To get most-recent listings:
/listings/home
This will return a JSON object similar to this:
{
"listings": [
{
"condition": "good",
"price": 27.99,
"listing_id": 2,
"status": "selling",
"timestamp": "2018-04-16 19:57:35.568820"
},
{
"condition": "ehh",
"price": 24.99,
"listing_id": 1,
"status": "selling",
"timestamp": "2018-04-16 19:57:26.674665"
}
],
"google_tokens": [
"1A"
],
"isbns": [
1
]
}
Notice that the listings are in order from most to least recent. From here, the user and book objects will be loaded separately. Use the data from those queries to construct the full home page.
7. Deleting Objects¶
To delete a user, send a DELETE request to:
/user/google_token_of_user
To delete a listing, send a DELETE request to:
/listing/listing_id
I don’t forsee us wanting to remove book objects from the database (at least
for the MVP), but it works as you’d expect: Send a DELETE request to:
/book/isbn