4. API App v2026.fa¶
Notice
This document contains the description for the API App project assigned to the students in the Fall 2026 CSCI 1302 classes at the University of Georgia.
4.1. Project Deadlines¶
This project has one set of deliverables. Submit it on or before Friday, December 4th @ 11:55 PM Eastern. The earlier deadline options below offer submission-based extra credit; they are not separate required submissions.
There are three different deadline options for this project. Students who perform their final submission via the appropriate submit command before the date/times listed below in Table 4.1 will automatically receive the associated Submission-Based Extra Credit (SBEC).
Option |
Due Date |
Extra Credit |
|---|---|---|
1 |
Tuesday, December 1st @ 11:55 PM Eastern |
+10 SBEC |
2 |
Thursday, December 3rd @ 11:55 PM Eastern |
+5 SBEC |
3 |
Friday, December 4th @ 11:55 PM Eastern |
+0 SBEC |
Late Submissions
The usual late-work policy does not apply to this project. No late submissions will be accepted after Deadline Option 3. Final submissions received after that deadline will not be graded.
4.2. Project Preface¶
Read this entire project description before beginning your project.
Academic Honesty
You agree to the Academic Honesty policy as outlined in the course syllabus and the University's honesty website. Furthermore, you must adhere to the book's copyright and licensing information.
Updates
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.
Learning Outcomes
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).
No use of JsonArray, JsonElement, JsonObject, and JsonParser
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 chapter.
No use of the openStream() or similar methods in URL
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 chapter.
Use of other types in the java.net.http package is allowed if they
are used to support HttpClient, HttpRequest, and/or
HttpResponse<T>.
Final Submission Deadline
The final submission deadline is Deadline Option 3: Friday, December 4th @ 11:55 PM Eastern. This is the final cutoff, including during finals week.
Amended Late Work Policy
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.
Non-Discrimination and Anti-Harassment Policy
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.
Private GitHub-hosted Git Repository
Each student is required to set up a private GitHub-hosted Git repository for their project. Instructions are provided later in this document.
Working on a Local Machine
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.
Use JDK 25 and Apache Maven 3.9 or later for local development. Maven must run on JDK 25 as well. Check both commands before building:
java -version
mvn -version
The starter project's Maven configuration supplies JavaFX 25.0.5 and Gson 2.15.0. Your application must still compile and run on Odin; these local requirements do not replace that grading requirement.
All other dependencies are handled via Maven.
4.3. Project Description¶
Your goal is to implement, from scratch, an application that automates the process of querying two different RESTful JSON APIs using JavaFX, custom components, HTTP requests, and JSON parsing.
Introduction
In other words, your app will showcase each RESTful JSON API by providing a way to let users interact with them without having to write the code to send the API requests (i.e., the HTTP requests to each API) themselves. Your app needs to do more than just download and display responses from the external APIs, it needs to include and incorporate at least two custom components for each API: i) one for gathering the user input that will be used as part of the HTTP request to the API; and ii) one for showing the response in a "visual" way (more on that later). You are allowed and encouraged to include additional custom components, but having them is not strictly required. The APIs can be related so long as they meet other requirements (see below for more details).
Additionally, you must use Java 25, JavaFX, custom components strategy, GSON, and the HTTP classes/interfaces discussed in the book.
You must choose your APIs and set up your custom components according to the following guidelines. Failure to do so may have a negative impact on your project grade.
Choosing Your APIs
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 in the 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 are required to showcase two 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:
Does the API method that you are trying to call have a way to adjust the request (e.g., by changing parts of the URI, by setting an HTTP header, or by using a POST request) to make a request?
Does the API method that you are trying to call return a JSON-formatted response?
Does your app directly access the API using an HTTP request (in the same way described in the textbook). You should be using the URI provided by the API itself - not using a third-party service such as Rapid API (or similar) for access.
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.
Custom Input and Visual Response Components
Your app must showcase two RESTful JSON APIs using custom components in a "visual" way.
For each API, you need to be able to answer yes to the following questions:
Does your app provide a custom component that includes the necessary nodes to permit the user input that will be used to adjust the API requests? This can be a small set of values typed in, selections made by the user, or combinations thereof that must be directly used to adjust the API request. Note: each user input must be a value/selection. Having the user press a button to start the process is not sufficient. You can have a button, but it cannot be the only form of input.
Is some part (or all) of the JSON response displayed to the user using a custom component in a "visual" way? Here is what the instructors do NOT want to see: show the response as a giant string using one or more text fields, text areas, text flows, labels, etc. Here is what the instructors DO want to see: any text from the response that is shown to the user should be organized using labels and parent nodes (e.g.,
HBox,VBox, etc.), and images should be displayed usingImageobjects viaImageViewnodes when appropriate.
User Experience and Credentials
It must be clear to users which API they are querying and viewing the response for at any given point. Your app may show both APIs at the same time (so long as your app does not exceed any size requirements mentioned elsewhere) or let the user switch between APIs (without having to restart your app).
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.
Rate Limits
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 you 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 to reduce the rate of requests 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.
Working with API Keys
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_KEY
If the API key needs to be set using an HTTP header, then refer to the example involving the GitHub API in the HTTP reading in the course textbook.
Planning Your Application
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 in 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.
4.4. Project Checklist¶
Use this checklist to organize your work. These stages lead to one final submission; they do not introduce separate submission deadlines.
1. Set Up and Run the Starter Code
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. For example, the URL has the formgit@github.com:YOUR-USERNAME/cs1302-api-app.git: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-app
You 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 --rebase
If 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 main
In 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. By default, therun.shscript is setup to automatically run thecs1302.api.ApiDriverclass when no command-line arguments are provided:$ ./run.sh
Here is the expected terminal output, which also shows the related Maven commands, should you wish to type them out manually:
+ mvn -q clean compile verify + mvn -e -q exec:exec -Dexec.mainClass=cs1302uga.api/cs1302.api.ApiDriver
If you wish to run another driver class, then you can supply its FQN as a command-line argument after the script name. For example, to run the
PropertiesExampleclass included with the starter code, run:$ ./run.sh cs1302.api.example.PropertiesExample
Here is the expected terminal output, which also shows the related Maven commands, should you wish to type them out manually:
+ mvn -q clean compile verify + mvn -e -q exec:exec -Dexec.mainClass=cs1302uga.api/cs1302.api.example.PropertiesExample
For completeness, it should be noted that you can also run
cs1302.api.ApiDriverby explicitly supplying its FQN as a command-line argument when using therun.shscript:$ ./run.sh cs1302.api.ApiDriver
2. Choose and Investigate Your APIs
Suggested readiness checkpoint: Friday, November 20. Before Thanksgiving break, aim to select both APIs, try sample requests, and sketch your custom components. This checkpoint is ungraded and does not require a submission.
Read Appendix: Working with RESTful JSON APIs and choose two RESTful JSON APIs from the required list in the Project Description. Check their request parameters, JSON responses, authentication requirements, and rate limits before planning your custom components.
3. Implement and Test Your Application
Implement the input and visual response components described above. Check every functional and non-functional requirement below. Test repeated requests to both APIs, handle errors, and communicate any intentional rate-limit delays to the user. Use Appendix: Git Feature Branch Workflow for guidance on developing features in separate branches.
4. Prepare and Submit
Update meta/DEADLINE.md and meta/ATTRIBUTION.md, check code style,
and follow Submission Instructions to commit, tag, push, and submit
your completed project on Odin.
Supporting Readings
4.5. Functional Requirements¶
A functional requirement is added to your point total if satisfied. This assignment is worth 100 points.
Primary Functions (90 points)
Your app must showcase two or more external RESTful JSON APIs as described earlier in the project description. 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.
Multiple Uses per Execution (10 points)
After the application is started, your application should allow the user to query each API 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.
4.6. Non-Functional Requirements¶
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.
Development Environment (100 points)
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.
API Access (100 points)
Your app must directly access each API using HTTP requests as described above.
User-Friendly Experience (10 points)
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.
Private GitHub-hosted Git Repository (20 points)
Each student is required to set up 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.
DEADLINE.md (10 points)
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.
Local Assets / Resources (10 points)
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 |
|---|---|
|
|
|
|
Code Style (20 points)
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.
Attribution (10 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.
4.7. Submission Instructions¶
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.
1. Update Your Project Documentation
Update your project's meta/DEADLINE.md. Specific instructions for
what to include in the update are contained in the file itself.
2. Commit, Merge, Tag, and Push
Merge all of your work in progress into the main branch, then tag
your main branch 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 --tags
NOTE: 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.
3. Check Style and Submit on Odin
CRITICAL: For this deadline, you also need to submit on Odin. Use
the submit command to submit your project on Odin for this
deadline:
Check for style guide violations:
$ check1302 cs1302-api-app/src/main/java
NOTE: 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-1302
NOTE: 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.
4.8. Frequently Asked Questions¶
Below are some frequently asked questions related to this project.
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 25, 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.
Examples of Projects that would not be allowed
Get and display random image of a dog from the Dog API without the user modifying the request in any way.
Ask the user to enter their latitude and longitude.
Showcases an API that responds with image data (instead of JSON).
Your custom component is essentially showing terminal/console output without presenting it in a nice, "visual" way, as described earlier in this project description.