Call and Response

[Dwebs911]

Flesh out the sample call and response sections

[NathanCarriere]

I wrote up 2 ideas for what we can do with this. The second idea here is meant to be an improvement on idea 1.

I made these quite specific since the prof described in class that the JSON output is what she meant by "resources", and also because the assignment states that the resources need to be detailed and JSON-formatted.

Example Resources Idea 1

{"results" { "Provided_City":"Winnipeg", "Provided_Address":"1 Main Street", "Provided_Postal_Code":"R3T2M5", "Address_Resolved":"true", "Temperature_Celcius":"-5", "City_Population":700000, "Sunrise_Time":[UTC-formatted time? Or Manitoba time?], "Sunset_Time":[UTC, or Manitoba?], "City_Elevation_Metres": 1000 } status: "OK" }

Explanation:

• I think it would be useful to the user to know whether the information is address-specific, so I included an "Address_Resolved" flag. An alternative to this could be a parameter that tells us whether to return "BAD REQUEST" if the address isn't resolved, or whether to just guess.

• For sunrise/sunset time, I'm not sure whether we should use UTC or local time (or both). Maybe it would be a good idea to have two additional outputs called "Sunrise_Time_Local" and "Sunset_Time_Local"?

• I also included measurements in the names so that it is obvious what they are.

My concerns with this idea:

• What happens if the postal code and city do not cover the same region? (I think in this case, city name should take priority)
• What if the address and postal code are in the same city, but the address is not located within the given postal code? (In this case, I think postal code should take priority)
• An explanation of these issues seems like they would extend our Part 1 beyond 300 words. I think we should consider changing our parameters so we can avoid having to explain "address vs postal code conflict" to API users. I think that removing "address" as a parameter would help resolve this. To get to the minimum required parameters/endpoints from here, I think having different parameters called "population", "sunrise", "sunset", etc would still meet assignment requirements.

Call/Resources Idea 2:

Based on issues from 1:

call: /info?city=Winnipeg&postal_code=R3T2M5&temp=true&pop=true&sunrise=true&sunset=true&elev=false (with city being the only required param)

response: {"results" { "Provided_City":"Winnipeg", "Provided_Postal_Code":"R3T2M5", "Temperature_Celcius":"-5", "City_Population":700000, "Local_Sunrise_Time":[local time], "Local_Sunset_Time":[local time], } status: "OK" }

Explanation:

• This idea adds simple and easy-to-explain parameters, and removes the address parameter. I think removing the address parameter removes most of the concerns I have with idea 1, particularly with how much explanation would be needed. While this does add a few parameters, they will be simple to describe. If they cause us to use too many words, we could always remove a parameter or two (I don't think we lose marks for having an API that doesn't do much).

• If the city and postal code disagree here, we have two options: 1. city will takes precedence and we return "status OK", or 2. we notice that bad information was sent to us, and we return "BAD REQUEST". I think BAD REQUEST would make more sense.