This document contains the description for the cs1302-api-app project assigned to the students in the Spring 2024 CSCI 1302 classes at the University of Georgia.
Please read the entirety of this file before beginning your project.
This project has three deadline options. Students who perform their final submission via the submit command before the date/times listed below automatically receive the associated Submission-Based (SB) extra credit.
| # | Bonus | Deadline Option |
|---|---|---|
| 1 | +10 | SAT 2024-05-04 (MAY 04) @ 5:00 PM EST |
| 2 | +5 | SUN 2024-05-05 (MAY 05) @ 5:00 PM EST |
| 3 | +0 | MON 2024-05-06 (May 06) @ 5:00 PM EST |
For both logistical and policy-related reasons, the usual late-work policy will not apply for this project, and no late submissions will be accepted after the last deadline option mentioned above. To be clear, final project submissions received after the last deadline option will NOT be graded.
You agree to the Academic Honesty policy as outlined in the course syllabus and the University honesty website. Furthermore, you must adhere to the copyright notice and licensing information at the bottom of this document.
If any updates to this project are needed after it is released, then they will be announced on Piazza. Updates related to correcting typos will probably not be announced unless they change the meaning of some requirement.
Your goal is to implement, from scratch, an application in Java 17 using JavaFX 17 that incorporates a preponderance of the topics introduced in this course in a way that demonstrates that you have met the learning outcomes related to those topics.
Your application must integrate two or more external RESTful JSON APIs so that your users don't need to utilize multiple services themselves to get the information or content that they want. Your app needs to do more than just download and display responses from the external APIs, it needs to combine the responses in some meaningful way. Combining responses means that the response from one API should be used (at least in part) to query the second API (see below for more details). Your application must automate the process of connecting two different APIs for a single purpose.
-
Many services provide free access to their RESTful JSON APIs -- a RESTful JSON API is one that you can access with an HTTP client (like
java.net.http.HttpClient) and parse with a JSON library like Gson. For this project, you may only use RESTful JSON APIs and no other kinds of APIs.You can find hundreds of APIs on the web; however, for this project, you must pick your APIs from this list:
Please note that the list above is a public resource and that not every API listed has been tested by the instructional staff nor guaranteed to be safe for work. All of the APIs list should, however, offer full, free access or at least a free access tier and do not depend on the purchase of a device/service before a request can be made.
Please make sure you only use APIs that are safe for work and adhere to the Non-Discrimination and Anti-Harassment Policy mentioned later in the project's requirements.
-
You must choose your APIs according to the following guidelines. Failure to do so may have a negative impact on your project grade:
-
You are required to integrate two or more RESTful JSON APIs from the "public-apis" list above in your final project submission.
For each API, you need to be able to answer yes to the following questions -- they are all questions that can be self-determined based on the project description, its appendices, the related readings, and what you learned in class:
- Does the API method that you are trying to call have a URI associated with it that can be adjusted (e.g., by changing parts of the URI or by setting an HTTP header) to make a request?
- Does the API method that you are trying to call return a JSON-formatted response?
NOTE: The APIs that you pick must NOT require "OAuth" for authentication (for each API on the "public-apis" site, there is a column indicating if OAuth is required). It is okay if an API key is required, and we even include an example that demonstrates how to make a request involving an API key in the appendix. If you use an API that requires an API key, then it is your responsibility to make sure you familiarize yourself with any restrictions associated with the API key. We also strongly encourage you to NOT pick an API that requires you to pay for an API key.
-
Your app must integrate the two APIs in a meaningful way.
For each API, you need to be able to answer yes to the following questions -- they are all questions that can be self-determined based on the project description, its appendices, the related readings, and what you learned in class:
- Is user input used to adjust your first API request?
- Is some part (or all) of the JSON response to your first API request used to adjust your second API request? The response can be modified by your application before being sent to the second API. The input used for the second API (i.e., the information used to adjust the request) must be different from the input used for the first API -- the inputs can share something in common, but they cannot be the same.
- Does the JSON response to the second API request provide you with one or more pieces of information that are NOT included in the response from your first API request?
The last question implies that both APIs must play an important role in the overall process that is automated by your app -- it should NOT be possible to implement the functionality of your app using only one of the APIs that you specifically selected.
Additional Notes: There are some additional things that you should consider that are not explicitly stated in the project description:
-
The users of your app must not be required to provide their own credentials to any service in order for it to function (e.g., a username, password, or API key). Your app may incorporate your API keys, if needed, as described in the appendix of the project description.
-
You are responsible for dealing with rate limits imposed by the APIs that you use. Many APIs have a limit on the number of API calls that can be made by an app (e.g., number of calls per second, per day, or in total). Please take precautions when using such APIs in your project so that we can grade it. There is no way for us to specify the exact number of times that we will run your app when grading it. If your app exceeds any rate limits while grading, then we will be unable to evaluate it.
SUGGESTION: To reduce the risk that you will exceed a rate limit, you are encouraged to write code to let your app keep track of the number of API requests that it has made over different periods of time and use that information to programmatically delay subsequent calls. For example, if your app includes a button that triggers multiple API requests, then should consider disabling the button while those requests are being made AND for some sensible extra amount of time after the completion of those requests in order to reduce the rate of request made by your app -- the exact amount of extra time will depend on the number of API requests your app makes as well as the rate limits imposed by the APIs. If your app needs to make more calls than it is allowed to make due to an API rate limit, then you may be able to introduce delays between requests to lower your app's request rate. Any extra waiting or intentional delays introduced by your app to deal with rate limits must be communicated to the user (e.g., you can adjust a label to say something like "intentionally waiting to deal with rate limits" whenever your program does either of these two things).
FURTHER READING: We have included some additional information here regarding how to check for rate limit values associated with an HTTP response.
-
-
Some of these API services do require you to register with them to gain access to an "API key" -- an API key is usually just a special string that is unique to you that must be incorporated into how you request the JSON response. For example, suppose you have an API key for the dog API stored in
API_KEY, then you might use the following URL when requesting the JSON for a list of breeds:"https://api.thedogapi.com/v1/breeds?apikey=" + API_KEYIf the API key needs to be set using an HTTP header, then refer to the example involving the GitHub API in the HTTP reading posted earlier this semester.
-
You should read the "Working with RESTful JSON APIs" appendix section before you write any code. A link to the appendix can be found later in this project description.
You have a lot of flexibility with regard to the functionality and visuals of your app. So long as your app functions and you meet the other requirements, you are free to make the app look and feel however you want (keep it appropriate).
Remember, part of software development is being given a goal but not necessarily being given instruction on all of the details needed to accomplish that goal. For example, even though working with things like API keys have not been explicitly covered in class, you are going to need to look up how to do these things to complete this project.
Here are some of the learning outcomes for this project:
- Plan, design, implement, test, debug, and deploy a complete object-oriented software solution in a Linux/Unix environment (1302-LO1).
- Utilize inheritance and polymorphism in a software project (1302-LO3-LO4).
- Develop a GUI for a software project (1302-LO7).
- Implement exception handling in a software project (1302-LO8).
- Understand and apply language basics using an OOP language (1302-LO11).
A functional requirement is added to your point total if satisfied. This assignment is worth 100 points.
Your app must integrate two or more external RESTful JSON APIs based on user input and combine the responses in some meaningful/interesting way. Combining responses means that the response from one API should be used (at least in part) to query the second API. Your application must automate the process of connecting two different APIs for a single purpose. Failure to meet this requirement will result in a grade of 0 for this category. If you have questions about whether or not your idea is sufficient, please discuss it with an instructor.
After the application is started, your application should allow the user to query the API(s) an arbitrary number of times without requiring them to exit and rerun the application. By arbitrary, we mean that there is no limit to how many times the user may do this.
A non-functional requirement is subtracted from your point total if not satisfied. To emphasize the importance of these requirements, non-compliance results in the full point amount being subtracted from your point total. That is, they are all or nothing.
This project must compile and run correctly on Odin using the specific version of Java that is enabled by the CSCI 1302 shell profile. For this requirement, the term compile should be interpreted as compile with no errors or warnings.
You must directly access any APIs used in your project. You are not allowed to use third-party services such as Rapid API (or similar) for access.
The windows of your application should not exceed a pixel dimension of
1280 (width) by 720 (height). Additionally, except for reasonable
delays resulting from X forwarding, your application should not
hang/freeze or crash during execution.
NOTE: If a grader encounters lag, then they will try to run your application locally after first checking that it compiles on Odin.
Each student is required to setup a private GitHub-hosted Git repository for their project. Failure to make your repository private will result in a 20-point penalty. If you are unsure whether your repository is private, ask an instructor or TA to visit the main URL of your project.
Reminder: Hosting any CSCI 1302 assignment in a public repository may lead to an academic honesty violation.
The included DEADLINE.md file must adequately describe your application,
explain the APIs used (the URLs used to request data, and the rate limits (if any)),
and provide thoughtful comments on what you learned. More
details can be found in the provided
DEADLINE.md template.
All assets (e.g., images), except for assets discovered using an
external API, need to be pre-downloaded and placed either in the
resources (not src/main/resources) or a directory under resources.
This will help make your app faster. Here are some examples that
illustrate the relationship between the path for a resource and the
file: URL that you need to use in your code:
| Resource | URL |
|---|---|
resources/icon.png |
"file:resources/icon.png" |
resources/foo/img.png |
"file:resources/foo/img.png" |
Every .java file that you include as part of your submission for this
project must be in valid style as defined in the CS1302 Code Style
Guide. All of the
individual code style guidelines listed in the style guide document are
considered for this requirement.
If check1302 on Odin reports any style violations for your submission,
then 5 points will be subtracted from your earned point total for each
violation, up to a maximum deduction of 20 points.
Proper attribution should be given for all assets (e.g., art, sound,
music, etc.) that you include in your project, especially assets that
you did not personally author. All such attributions need to be placed
in the meta/ATTRIBUTION.md file.
For each asset that you authored, please provide the following information:
* Asset Name
- `resources/path/to/file`
- Your Name. Year.
For each asset that you did not personally author, please provide the following information:
* Asset Name
- `resources/path/to/file`
- Author. Year.
- URL
- License
NOTE: Don't forget to stage and commit your meta/ATTRIBUTION.md file after
you update it!
You may NOT use or mention the following classes provided by Gson:
com.google.gson.JsonArraycom.google.gson.JsonElementcom.google.gson.JsonObjectcom.google.gson.JsonParser
To parse a JSON-formatted string, use a Gson object's fromJson method to parse
the string directly into an instance of a class that you created to represent the
object described by that JSON-formatted string. Classes for an iTunes Search response
and result are provided with the starter code. Instructions for parsing JSON-formatted
strings using fromJson are described in the
JSON reading.
You may NOT use or mention the openStream(), openConnection() and getContent()
methods provided by the java.net.URL class nor should you use or mention java.net.HttpURLConnection.
If you need to access web content, then use the HttpClient, HttpRequest, and HttpResponse<T>
types in the java.net.http package as described in the
HTTP reading. Use of
other types in the java.net.http package is allowed if they are used to support HttpClient,
HttpRequest, and/or HttpResponse<T>.
Per university policy, each student must be provided the opportunity to stand for a final examination as part of the completion of a full instructional term, and instructors have the authority to design and administer the final examination for a course in whatever manner is appropriate. In CSCI 1302 this semester, the final project described by this document will be treated as the final examination since the grade and feedback that a student receives for this assignment is a summative evaluation of the entire term's work.
Please take care to note the date/time for the final submission deadline, Deadline Option 3. In particular, the deadline time is earlier in the day compared to previous projects.
For both logistical and policy-related reasons, the usual late-work policy will not apply for this project, and no late submissions will be accepted after Deadline Option 3. Final submissions received after Deadline Option 3 will NOT be graded.
Since this project affords you more flexibility with respect to the content of your app, you are reminded that, as a UGA student, you must conduct yourself in accordance with the UGA Code of Conduct and the UGA Non-Discrimination and Anti-Harassment Policy.
Each student is required to set up a private GitHub-hosted Git repository for their project. Instructions are provided later in this document.
If you decide to work on part or all of the project on your local machine, then it's your responsibility to ensure that your environment is compatible with the versions of software on Odin. No technical assistance will be provided by the instructional staff to accommodate this beyond the information provided in this policy statement. Remember, your code still needs to compile and run on Odin per the "Development Environment" absolute requirement. That is, if your submission does not compile on Odin, then that will result in an immediate zero for the assignment. A list of the relevant software versions currently in use on Odin (at the time of this writing) is provided below for convenience.
-
Apache Maven 3.9.6 (https://maven.apache.org/)
-
Java 17.0.10 (vendor: Oracle Corporation; not OpenJDK) (https://www.oracle.com/java/technologies/downloads/)
All other dependencies are handled via Maven.
Downloading the starter code for this project requires more steps compared to earlier projects. These instructions assume that you have completed the steps in "Setting up SSH Keys" to set up your public and private key pair on Odin and GitHub.
-
If you have not done so already, you should create a free GitHub-hosted private Git repository for your project under your GitHub account called
cs1302-api-appand note its SSH URL. Here is an example:
Remember to note the SSH URL!
NOTE: In the remaining instructions,
REPO_SSHrefers to the SSH URL for the private repository you created on GitHub. -
Clone your empty private repository to your Odin account.
$ git clone REPO_SSH cs1302-api-appYou should now have a directory called
cs1302-api-appin your present working directory.NOTE: If you get an authentication error, then that means that you did not set up your public and private key pair on Odin and GitHub prior to following these instructions. Instructions for this are provided in the "Setting up SSH Keys" reading.
-
Set up a remote link to the repository containing the starter code. A sequence of commands is provided below. You should make every effort to understand what each command is doing before you execute the command:
$ cd cs1302-api-app $ git branch -M main $ git remote add starter https://github.com/cs1302uga/cs1302-api-app.git $ git pull starter main --rebaseIf you followed these instructions correctly, then your present working directory (you should still be inside
cs1302-api-app) now contains the starter code and a.gitdirectory. -
You should think of the
cs1302-api-appdirectory on Odin as your local copy of the project. As you add, stage, commit, branch, etc., those changes are only local to that copy of the project -- they do not automatically appear on the GitHub page for your repository. To send changes to GitHub, follow these steps:-
Use
git statusto ensure that you are on themainbranch and fully committed. If you're not, then take the necessary steps to make sure that you are. -
Push changes to GitHub:
$ git push origin mainIn your browser, revisit your GitHub-hosted private Git repository. Instead of an empty repository, you should now see the starter code.
You can follow the steps above any time you want to send your local changes to GitHub.
NOTE If you have trouble getting any of this to work, then try asking on Piazza or see someone during office hours.
-
-
Clean, compile, and run the starter code using the provided
run.shscript:$ ./run.shHere is the expected output, which also shows the related Maven commands, should you wish to type them out manually:
+ mvn -q -e clean + mvn -q -e compile + mvn -q -e exec:execBy default, the project is setup to automatically run the
cs1302.api.ApiDriverclass. If you wish to run another driver class, then you can provide the simple class name of a class with amainmethod in thecs1302.apipackage after the script name:$ ./run.sh PropertiesExampleAny other command-line options that you add after the script name will be added to the end of the
mvncommand that executesexec:exec.
You will be submitting your project via Odin before the last deadline
option indicated near the top of this document. Make sure your project
files are on odin.cs.uga.edu.
-
Update your project's
meta/DEADLINE.mdSpecific instructions for what to include in the update are contained in the file itself. -
Merge all of your work in progress into to the
mainbranch, then tag yourmainbranch for this deadline as described below.-
Ensure that whatever branch you are on is fully committed (i.e.,
git statussays there is nothing to commit). -
Checkout the
mainbranch.$ git checkout main -
If needed, merge changes into
mainfrom the branch you were working on following the instructions provided in the "Git Feature Branch Workflow" appendix section. -
Tag your
mainbranch by executing the commands below:$ git tag -am "deadline" deadline $ git push origin --all $ git push origin --tagsNOTE: Take special care to ensure that your fully-committed
mainbranch reflects the project you wish to submit. Compare your log to the log on GitHub. If your GitHub repository does not have the most recent version of your project, then you may need to do agit push origin mainwhile on yourmainbranch.NOTE: If you need to make more commits and retag, then use an
a,b,c, ... suffix in the tag names (e.g.,deadline-a,deadline-b, etc.).NOTE: Evidence of branching and merging is encouraged for this deadline. When inspecting your Git log, the graders would like to see that you made proper use of
branch,checkout, andmergeto work on portions of your project prior to including those changes in yourmainbranch. More detailed instructions are provided in the "Git Feature Branch Workflow" appendix section.
-
-
CRITICAL: For this deadline, you also need to submit on Odin! Use the
submitcommand to submit your project on Odin for this deadline:-
Check for style guide violations:
$ check1302 cs1302-api-app/src/main/javaNOTE: If there are style guide violations, then checkout a new branch, fix your code, commit, test your program, potentially fix some more, commit, then checkout
mainand merge in the beautiful code from the branch you were just in. You should also retag and push yourmainbranch as described elsewhere. Once you have no style guide violations, you can proceed to the next step. -
Perform your final submission:
$ submit cs1302-api-app csci-1302NOTE: If you have any problems submitting your project, then please contact the CSCI 1302 Support Team by sending a private post to "Instructors" via the course Piazza as soon as possible.
-
Below are some frequently asked questions related to this project. You may also find the cs1302-gallery FAQ_ a useful resource as well.
-
May I use an API not mentioned in the project description?
-
RESTful JSON API
No, your APIs must come from the provided list.
-
Java API
If you're asking about a third-party Java API that is not included with Java 17, JavaFX, Gson, or the starter code, then the answer is NO.
-
-
How do I add sound?
While JavaFX does support audio playback of various formats, this feature is not currently available over X11 forwarding from Odin. We're sorry to say this, but you should not attempt to add audio to your application for this project.
Copyright © Michael E. Cotterell, Bradley J. Barnes, and the University of Georgia. This work is licensed under a CC BY-NC-ND 4.0_ license to students and the public. The content and opinions expressed on this Web page do not necessarily reflect the views of nor are they endorsed by the University of Georgia or the University System of Georgia.
Feature Preparation Timestamps: