API Requests Structure [WIP]

[shayna-k]

General ideas for the requests we will handle:

GET:

1. Get all poems

endpoint URL: /api/poems description: Get all poems,

request optional URL parameters

param	description	example
author	the author of a poem	nick
loc	GPS coordinates	41.78868316205326, -87.59874232864101
radius	distance from "loc" in meters	20
route	the CTA bus route number	172

an example of a request with specifc params set might be:

/api/poems?loc=121.121029,23.1029381208&radius=20&author=nick

the request above will return an array of poem objects written by "nick", 20 meters around the given GPS coordinates (121.121029, 23.1029381208)

response returns an Array of poem objects which look like the following:

 {
  datetime: 1668544391012, // number, unicode timestamp
  location: [41.78868316205326, -87.59874232864101], // Array of GPS coordinates
  text: "an example poem", // string
  author: "Bobby Bob", // string,
  route: 172 // number, a bus route
 }

POST:

1. Post poem

endpoint URL: /api/add-poem description: Post a poem to the database

request needs to contain a JSON object for a poem in the POST request which looks like:

 {
  datetime: 1668544391012, // number, unicode timestamp
  location: [41.78868316205326, -87.59874232864101], // Array of GPS coordinates
  text: "an example poem", // string
  author: "Bobby Bob", // string,
  route: 172 // number, a bus route
 }

response if everything went smoothly on the backend

{
  success: true
}

if there was an issue, the API will return an error

{
  success: false,
  error: "an error message"
}

[bermanisaac]

@shayna-k Could we also add a request to get poems from a certain route or a certain bus number? That should be pretty similar to requests already included, but might be nice to have this functionality as well. I've also sent a comment to the database team to ask about storing this info as well.

I really like the idea that we could send users poems written on the same physical bus they are riding, even if those poems were written when that bus was serving a different route. The CTA API provides us with unique bus numbers that we should be able to track and associate with a poem.

[shayna-k]

@bermanisaac this sounds good! Updated the issue with a placeholder note to be edited later based on how the data will be stored