Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
78 lines (63 sloc) 8.36 KB

CMSI 370 Interaction Design, Fall 2019

Assignment 0919b

Conceptually, this assignment is integral to the front-end design and white paper, but its content and tasks are sufficiently distinct that they work better as a separate deliverable.

In order to turn your front end design into a reality, you will need to learn how to work with the web service API that provides its functionality (the utility, in Nielsen’s terms). For many of you, this will be your first time doing this, so this assignment is meant to give you some structure for learning how to do it.

Background Reading

A lot of information is available on the web for how to interact with web services, but to save time, the most relevant information has been gathered into a primer that accompanies the assignment repository, so most importantly, read that primer. The how-to on this document is meant to be self-contained, so reading this and following along the supplied walk-throughs serves as your best starting point.

After that, performing web searches on how to use specific technologies (curl, Postman, window.fetch) should help supplement the information here. Some starting points, hosted by the home sites of these technologies:

For Submission: API Setup/Tutorial Document

For this part of the initial design and preparation work for your front end, acquire some hands-on experience with the web service API(s) that your front end will use. The intent of this assignment is to have you:

  • Learn how to send requests and interpret responses to and from a web service
  • Document that you did learn how to do this and practiced this enough to be ready for implementation
  • Identify potential issues with your chosen web service API(s) so that we can take steps to resolve them

To accomplish this, do the following:

  1. Fully read A Primer on Interacting with Web Service APIs
  2. Read the documentation of the web service(s) you intend to use for your front end
  3. If needed, sign up for an account with said web service(s)
  4. Use curl or Postman (or both) to send requests to the web service(s)
  5. Use window.fetch to send requests to the web service(s)
    • Note how you may choose between curl or Postman for initial practice, but you must also use window.fetch
    • The reason for this is that window.fetch runs within a web browser, and there are aspects of interacting with a web service API that are specific to their use in a browser (e.g., CORS)
    • Another reason is that those of you who will build a web app for your front end will be using window.fetch in the app code itself—thus, this assignment serves as a preview for that
  6. Learn to read and understand the responses that you get back
  7. Write up a report showing that you sent the requests that you plan to use and can point out the data that will be needed by your front end within their responses
    • Many web service APIs will give you an API key or other credentials in order to use them—normally, these should not be posted on any websites or repositories, but because your assignments are private and this information will be needed for verification and grading, make an exception in this case and make sure to provide this information in your report
  8. Include examples of your own requests and responses in the document via screenshots
    • This is another reason for making an exception with supplying API keys or credentials—screenshots of real requests and responses will have this information anyway
    • Genuinely perform these requests yourself, and don’t just appropriate screenshots from the documentation or the web, nor ask someone else to do it and grab their screenshots—not only is this academically dishonest, but it will be problematic later when you actually start to implement your front end

General Outline

Start your report with an “Executive Summary” section—essentially a TL;DR for the overall exercise. This section should give the reader a general sense for how things went.

Your report should then include the following information for every web service function that you plan to use in your front end. In other words, most reports should have three (3) sections that all look like this:

  1. Brief explanation of the web service function/endpoint
  2. Documentation/screenshots that you can send requests for this endpoint in Postman or curl
  3. Documentation/screenshots that you can send requests for this endpoint with window.fetch in a web browser
  4. Documentation/screenshots of the responses that you receive
  5. Brief explanation/navigation of the responses to point out the information that you plan to use
    • For JSON responses (which will be what most web services return), use a JavaScript expression rooted at the response (because it’s JSON after all; e.g., response.data[0].images.fixed_height.url)
  6. If applicable, document any issues or errors that you encountered, particularly with window.fetch
    • It is very possible that you will encounter success with Postman or curl but not with window.fetch—these, in particular, are the issues that we want to get a handle on
    • If you encounter problems with all mechanisms for making requests, then this is most likely “pilot error” (i.e., the tools aren’t being used in a way that matches the web service API specification) or a serious server reliability issue—for the former, resolving the issue is a matter of figuring things out; for the latter, this might be a signal that you are better off with a different (more reliable) web service
    • If no errors are encountered at all explicitly say so in order to be clear that you didn’t just forget to report them

If your front end will need more than three (3) distinct web service functions, you may choose any three to report back on. Note it will still be beneficial for you to try out all of the web service functions, just in case a problematic one is lurking among them outside of the three that you will document in this assignment.

How to Turn it In

Commit the tutorial in this repository under the filename api-setup-tutorial.md.

Specific Point Allocations

This assignment fits specific subsets of outcomes 3a, 3b, 4a, and 4c to 4f in the syllabus, and will mainly be scored according to the degree to which the content delivered aligns with the content requested by the instructions. Outcomes 3a and 3b apply here to the ability to work at the boundary where usability meets utility, which is what the web service calls represent. Outcome 4a applies to how correctly the tools are used (where window.fetch also counts as “syntactically correct, functional code”). For this particular assignment, graded categories are as follows:

Category Points Outcomes
Executive Summary 5 points 3a, 3b, 4d
Web Service Reports 25 points each, 75 points total
• Brief explanation 2 points 4d
• Postman or curl report and screenshots 5 points 3a, 3b, 4a, 4d
window.fetch report and screenshots 5 points 3a, 3b, 4a, 4d
• Response report and screenshots 5 points 3a, 4d
• Response navigation 5 points 3a, 4d
• Error report 3 points 4d
Writing deduction only 4c
Version Control deduction only 4e
Punctuality deduction only 4f
Total 80

As a writing assignment, outcome 4c is interpreted here as writing clarity and correctness instead of code readability. The last three graded categories are “deduction only,” meaning that you will only get points taken off if there are significant issues with those categories. Such issues include but are not limited to: unclear, unproofread, or erroneous writing (4c), insufficiently granular or unmessaged commits (4e), and late commits (4f).

You can’t perform that action at this time.