Description

HOMEWORK ASSIGNMENT 6
Abstract
Server-side Scripting using Python, Flask, JSON, AJAX, and Artsy API
Baskin Senbaslar
baskin.senbaslar@usc.edu
Homework 6: Server-side Scripting using
Python, Flask, JSON, AJAX, and Artsy API
1 Objectives
1. Get experience with Python programming language and Flask framework.
2. Get experience creating web pages using HTML, CSS and JavaScript. Understand DOM, use JSON format. Use fetch API or XMLHttpRequest for AJAX.
3. Get experience with Artsy API.
4. Get experience with Google Cloud Platform (GCP).
2 Homework Description Resources
1. Homework Description Document (This document)
2. Grading Guidelines
3. Reference Video: https://www.youtube.com/watch?v=99dILffDymo
4. Piazza
3 General Directions
1. The backend of this homework must be implemented in Python using Flask. For Python and Flask kick-start, please refer to the i) lecture slides on the class website and ii) Flask Quickstart documentation.
2. The backend of this homework must be deployed to GCP. See homework assignment 5 for deployment of your project on GCP.
3. You must refer to the homework description document (this document), grading guidelines, the reference video and instructions in Piazza while developing this homework. All discussions and explanations in Piazza related to this homework are part of the homework description and grading guidelines. Therefore, please review all Piazza threads before submitting the assignment. If there is a conflict between Piazza and this description and/or the grading guidelines, answers in Piazza are valid.
4. The homework will be graded using the latest version of the Google Chrome browser. Developing homework using the latest version of Google Chrome is advised.
4 Description
In this homework, you are going to create a web page that allows its users to search for artists using the Artsy API. The results of the search will be listed as a list of artist cards. When a user clicks on an artist card, details about the chosen artist will be shown underneath.
4-1 Artsy Developer Registration
To use Artsy API, you need to create a developer account in Artsy, create an app and get a client ID and a client Secret.
In your browser, navigate to https://developers.artsy.net/.
Click to the “Sign In” button on the top right of the page to navigate to login page.

Click on the “Sign up” button below the login page.

Fill out your information in the registration form. You don’t have to use your USC email. Click on the “Sign up” button.

Artsy will send you a confirmation email. Click on the “Confirm email” button in the received email.

Navigate to https://developers.artsy.net/. You should be logged in. If not, you can login by clicking the “Sign In” button on the top right corner.
Click on the My Apps button.

Click on the “Create a New App” button on the opened page.

Give a name to your app (it can be anything), and leave “Redirect urls” empty. Click on “Save” button.

Your new app will be listed in the “My Apps” page. Click on the “edit” button near the app you just created.

Save “Client ID” and “Client Secret” values to a document on your machine. You will use them to make requests to Artsy.

4-2 Artsy API Endpoints
The full list and documentation of Artsy API endpoints are given in https://developers.artsy.net/v2/. In this homework, you will use 3 Artsy API endpoints: Authentication, Search, and Artists.
Search and Artists endpoints requires X-XAPP-Token header, which you will get through Authentication endpoint.
4-2-1 Authentication Endpoint
{
“type” : “xapp_token”,
“token” : “…”,
}
The token field of the response will be used while accessing Search and Artists endpoints. Notice that the token returned from the Authentication API expires in 1 week. You can either implement a logic that refreshes the token when it expires (elegant solution) or get a new token before each request (not elegant solution). For the purposes of this homework, we will not grade how you implement this logic. You are free to do it either way.
4-2-2 Search Endpoint
Search endpoint allows you to search queries in Artsy DB. It has the base URL https://api.artsy.net/api/search. You send your request using HTTP GET method. It accepts query parameter q. You send your search query through this parameter. The maximum number of results can be set by size parameter, which has the maximum value of 10. In this homework, you will always set it to 10. In addition to the query parameter, you should set X-XAPP-Token header in your request to the token returned from Authentication endpoint.
Example request: https://api.artsy.net/api/search?q=picasso&size=10 The server returns a JSON result, excerpt from which is given below.

The search results are listed in [“_embedded”][“results”] field. Search endpoint returns search results across 5 types: artist, artwork, profile, gene and show. In this homework, we are only interested in artist results. After making a request to the Search API, you will filter results by choosing the ones with “og_type” equal to “artist”. The ID of artists can be extracted from the [“_links”][“self”][“href”] field of each result. The part after the last slash symbol is the ID of the artist. (e.g. if the artist link is https://api.artsy.net/api/artists/4d8b928b4eb68a1b2c0001f2, artist ID is 4d8b928b4eb68a1b2c0001f2)
Artsy search results are paginated, meaning that it returns a specific number of results after each request (set by the size parameter) and if the remaining results are wanted, another request can be made to the link in the [“_links”][“next”][“href”] field of the response. In this homework, you will only use results from the first page and will not make additional requests.
We are interested in [“title”] (name of the artist) and [“_links”][“thumbnail”][“href”] (image for the artist) fields as well as the IDs of artists in this homework. When an artist does not have an image, [“_links”][“thumbnail”][“href”] field contains “/assets/shared/missing_image.png”.
4-2-3 Artists Endpoint
Artists endpoint is used to get details about an artist. It has the base URL https://api.artsy.net/api/artists. You send your request using HTTP GET method. It accepts a query parameter id, denoting the ID of an artist. Differently from the Search API, you append the id parameter to the link without specifying the name of the parameter. (i.e. You send request to https://api.artsy.net/api/artists/{id}) Similar to the search endpoint, you should set X-XAPP-Token header in your request to the token returned from Authentication endpoint. Example request: https://api.artsy.net/api/artists/4d8b928b4eb68a1b2c0001f2 The server returns a JSON result as given below.

In this homework, we are interested in [“name”], [“birthday”], [“deathday”], [“nationality”] and [“biography”] fields of this response.
4.3 System Overview
The system contains three components: 1) browser (frontend), 2) Flask application (backend) and 3) Artsy servers. You will implement the frontend and the backend. Your backend will have two functionalities: serving the frontend static files to the browser and responding frontend’s AJAX requests by fetching data from Artsy servers. You will not directly call Artsy API from the frontend as it requires disclosing Client Id and Client Secret (and/or XAPP_TOKEN) to the public. The data flow diagram after an AJAX call is shown below.

Sending a request to anywhere except your backend from the frontend will result in a 4-point penalty. Please do not directly call Artsy API endpoints from your frontend.
All requests from frontend to backend must be implemented using HTTP GET method, as you will not be able to send us sample backend endpoint links as a part of your submission if you use HTTP POST.
4-4 Page Layout
The page contains a header section, a content section and a footer section arranged vertically.
The header section is a static bar containing site title “Artist Search” on its left. The footer section is another static bar containing Artsy attribution “Powered by Artsy.”, in which the Artsy logo is placed before the word “Artsy”. When Artsy text on the footer is clicked, the page is redirected to Artsy homepage.

Page Header

Page Footer
The content section contains the contents of the page, in which the following features will be shown.
4-5 Search Bar
When a user opens the page for the first time, there is only a search bar in the content section. Search bar contains three items: a magnifying glass icon on the left, an input section in the middle and cross icon on the right, shown below.

Search Bar
When the cross icon is clicked, the contents of the input section are cleared.
The magnifying glass icon and cross icon are partially transparent (Hint: Check opacity CSS property), and are made opaque when hovered as shown below.

Magnifying Glass Icon is Made Opaque when Hovered

Artist names can be entered into the input section of the search bar. The input section has the placeholder value “Please enter an artist name.”, which is shown when the input field is empty (Hint: Check placeholder attribute of input tag). When the input section is focused (i.e., input section is clicked and the cursor is blinking within the field), search bar’s border color should be made orange as shown below (Hint: Check CSS focus-within pseudo-class).

Search Bar when Input Section is Focused
User can initiate to search by either 1) clicking the magnifying glass icon or 2) by hitting enter key. If user initiates the search when the input text is empty, an alert should pop up showing the text “Please fill out this field.” in Google Chrome browser shown below (Hint: Check required attribute of input tag).

Search Bar when Search is Initiated without Input
When the search is initiated, your frontend will do an AJAX call to the backend, sending the input text. Upon receiving the request, your backend will make a request to Artsy Search API, forwarding the input text to Artsy Search API via parameter q as described in the Search Endpoint section above. Until a response is received from the backend, loading gif is shown below the search bar as shown below.

Loading Gif is Shown Until a Response Arrives
When the response arrives, loading gif is hidden and the results are shown in the result list.
4-6 Result List
The results of the search are shown as a list of cards. Each card contains the artist image with link retrieved from [“_links”][“thumbnail”][“href”] field of an artist result in the reponse of search endpoint.
Image is contained in a circular frame (Hint: Check border-radius CSS property) with white border. Below the image, the artist name is listed corresponding to the [“title”] field of the artist result. The list of result cards is scrollable. The cards have a blue background color (HTML Color Code: #205375).

Result List
If a particular artist does not have an image, Artsy returns “/assets/shared/missing_image.png” in the [“_links”][“thumbnail”][“href”] field as mentioned in Section 4-2-2. In this case, you will place Artsy logo as the artist image as shown below.

Artsy Logo is Shown if an Artist Does Not Have an Image
If the search results are empty, i.e. no artists match the given query, an error message containing text “No results found.” will be shown as below.

When a card is hovered, its background color changes to darker blue (HTML Color Code: #112B3C) as shown below.

The Background Color Change of a Hovered Card
When an artist card is clicked, your frontend will do an AJAX call to your backend to get artist details. In order to get artist details, you must send artist ID to the backend. For that, you have to associate artist IDs with cards, which you can do during initial search by sending artist IDs from your backend to the frontend as a part of the response. Until a response is received from the backend, loading gif is shown below the result list as shown below.

Loading Gif is Shown Until a Response Arrives
The selected card’s background color is permanently set to darker blue after the click, which denotes the active card for which details are being shown. It will remain darker blue until another card is selected, at which point the background color of the newly selected card will be set to darker blue and the original card’s background will set to original blue. (See Section 4-8 for different use cases) When the response arrives for artist details, you will hide the loading gif and show the artist details.
4-7 Artist Details
Details will include artist name, artist birth year, artist death year, artist nationality and artist biography. The details are presented as follows.

Artist Details
First line contains the name of the artist followed by birth and death days. Next line contains the nationality of the artist. Next, the biography is shown. These information correspond to [“name”], [“birthday”], [“deathday”], [“nationality”] and [“biography”] fields of the artists endpoint response. If any of the fields are empty, you should simply leave them blank. Examples are given below

No Biography, No Birth Year, No Death Year

No Nationality, No Death Year, No Biography

No Death Year, No Biography
4-8 Different Use Cases
When a user clicks on another search result while the details of an artist are being shown, the website will hide the artist details and show the loading gif below result list until a response arrives. The background color of the newly selected card will be set to darker blue, and the background color of the previously selected card will be set to original blue. When the response arrives, the details of the newly selected artist will be shown, and the loading gif will be hidden.
When a user searches a new artist using the search bar while the details of an artist are shown, the details will be hidden, background color of the selected card will not be changed and the loading gif will be shown under the list of results until a response arrives. In this case, search results will not be hidden, but they will be replaced whenever results arrive. When the response arrives, loading gif will be hidden and all background colors will be set to original blue.
When a user searches a new artist using the search bar while search results are being shown without any details, only the loading gif will be made visible until a response arrives. Search results will not be hidden, but they will be replaced whenever results arrive. When the response arrives, loading gif will be hidden. (Similar behavior as the paragraph above)
5 Homework Submission
In your course homework page, update the Homework 6 link to refer to your deployed website. Also, provide an additional link to one of your cloud query entry points, below the homepage link. Your project must be hosted on GCP. Graders will verify that these links are indeed pointing to GCP.
Also, submit your source code file to DEN D2L as a ZIP archive. Put your frontend and backend codes, plus any additional files needed to build your app (e.g., yaml file). The timestamp of your last submission will be used to verify if you used any grace days.
6 Notes
• You can use jQuery for Homework 6, but it is not needed.
• You cannot use Bootstrap for Homework 6. If Bootstrap is used, 4-point reduction will be applied.
• Appearance of the webpage should be like the reference video as much as possible.
• Artsy lacks information for a lot of artists. Most do not have biographies; some do not have nationalities. Here are some examples for testing:
7 Static Resources
Loading gif, Artsy logo, magnifying glass icon and cross icon can be found in https://csci571.com/hw/hw6/images/images.zip.
8 Hints
• You should use the domain name of the GCP service you created in HW #5 to make requests. For example, if your GCP server domain is example.appspot.com, https://example.appspot.com will become your base URL. The example subdomain in the above URLs will be replaced by your choice of subdomain from the cloud service.