parking api updates - possible contract change

[Chris Skudlarczyk]

Hello Madison Hackers,

Fresh off an update to the parking api, I would like to add campus lots and might need to change the v1 contract (error handling, payload, and possibly the route itself). If so, the choices i see are:

1. Create "v2" - (source location and route)
2. Change the existing v1 contract in-place which would potentially break existing consumers. Are there any current consumers of the parking api (besides http://parking.smsmybus.com/)?
3. I could probably implement in a non-breaking way but it will result in some clunkiness in the contract. 
   

My preference would be #1 but I don't want to move forward in a way that is inconsistent with your patterns. 

Whatcha think?

Thanks,

Chris

 

[Steve Faulkner]

1 seems to be the best option to me too. I'm not personally aware of any consumers, but breaking the current API is still a bad thing. 

--
You received this message because you are subscribed to the Google Groups "HackingMadison" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hackingmadiso...@googlegroups.com.
To post to this group, send email to hacking...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/9b483f80-19bc-4234-a8bd-a93bf5a42a6e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Greg Tracy]

I like #1 as well. 

Will you modify the endpoint structure - http://api.smsmybus.com/v1/getparking - at the same time? Or just the parameters?

Thanks!

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/CALSD8H%2B5EF%2BEbYeL4Aiu8QuconV1ukkE9mVU6uHsc_%2BSVZN%3D%3DA%40mail.gmail.com.

[Chris Skudlarczyk]

Google Groups is flat out getting the best of me lately... sorry if you receive a duplicate.

Greg, on the route, yeah, worth discussing. And although I'm only working on the parking api I do want to ensure my scheme would work for transit. I'm thinking something like this:

   - http://{domain}/{verson}/{resource-pluralized}/{id} -- (examples: http://api.smsmybus.com/v2/parkinglots/1234, http://api.smsmybus.com/v2/routes/1234)


An option worth considering is adding an "apiname" in the path. It would make a larger distinction between the parking and transit apis but not sure if that's enough for the extra segment of the path. I like it for parking but think it's less useful for transit and i want to be sensitive to anything that muddies transit. But if we went that route:
  
   - http://{domain}/{apiname}/{verson}/{resource-pluralized}/{id} - (examples: http://api.smsmybus.com/parking/v2/lots/1234, http://api.smsmybus.com/transit/v2/routes/1234)


Very open to feedback. Will post more details about the the api contracts soon.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/CAKPO1Efy-du19RU%3Di35EL3_erNa5ZZdkfc9qd-Wu23gJVXZoHQ%40mail.gmail.com.

[Greg Tracy]

The original route choices were really naive. I wouldn't do it the same if I had it to do over again. In fact, at one point, I surveyed the API devs to ask if they cared because I was ready to change it to be resource based as you've suggested. There wasn't any desire from the community so I left it as-is. 

I think I like the latter approach. The third candidate for the API is the local bike sharing service from Trek.

http://api.smsmybus.com/bikes/v2/stations/123

I'm not sure I'd invest time into the bus piece just yet.

Thanks!

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/CAO35DmXGsEPz1hfz0vfji4pA%3DCme6uwaZZXHYiLmfm3XqV5tYQ%40mail.gmail.com.

[Chris Skudlarczyk]

I just realized Google Groups is deleting my posts perhaps thinking they are spam so sorry about the late reply. Argh. 

Greg, good to know there could be more APIs added so yeah, having the api-domain in the path makes sense.

I'm not sure about what I proposed as the position of the version in the path, but we can tweak that easily. Could also add version to headers and yank it out of path... I don't have a strong preference either way and I see it both ways in the wild.

Very close to submitting a pull request. Feel a little bad cause it's going to be fairly big so I'll try to add some helper documentation to aide in the review process.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/CAKPO1Ed2i%2B8ta0v9oCMp58nzrdnhjtXH29e%3D7GgFVR0wk8g6zA%40mail.gmail.com.

[Greg Tracy]

I'm a fan of having the version in the path. It makes it very explicit and easy to test from a browser. 

Looking forward to the changes!

[Chris Skudlarczyk]

Hi all,

Just about to submit the pull request but there is one last item related to route params I'd like to run by you.

I came across it when considering whether to include special events by default. I think I would like to exclude it by default, one because it's expensive (although i cache it), but more so to give control to the consumer.

So i am treating special events as a distinct (but related) resource to a lot. The broader consideration is the way the API (SMSMyBus) would generally embed a related resource, which is why I'm raising it. The most common way of doing this seems to be the "expand=" convention.

To demonstrate how it is working now:

http://<myserver>/parking/v2/lots - lots only.
http://<myserver>/parking/v2/lots?expand=specialevents - lots plus special events embedded accordingly.

"expand" could handle an array of values: expand=specialevents,foo

It's also important to consider filtering. I would still just filter with key=value. For instance:
http://api.smsmybus.com/parking/v2/lots?operatedby=city - which would only return city operated parking lots.

And you could certainly do:
http://api.smsmybus.com/parking/v2/lots?operatedby=uw&expand=specialevents&specialeventsuntil=2014-05-17T18:05:00 - returns only uw lots with special events starting within the next 3 hours.

Does use of "expand=foo" seem like a reasonable way to embed resources?

I could very easily punt completely and revert my expand logic if this requires more consideration. I'm good either way.

Thanks!

On Tue, May 13, 2014 at 8:20 PM, Greg Tracy <gtr...@gmail.com> wrote:

I'm a fan of having the version in the path. It makes it very explicit and easy to test from a browser. 

Looking forward to the changes!

--
You received this message because you are subscribed to the Google Groups "HackingMadison" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hackingmadiso...@googlegroups.com.
To post to this group, send email to hacking...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/8facb1ea-dadd-4fa7-8849-a84a6726c2fe%40googlegroups.com.

[Greg Tracy]

Makes a lot of sense to me. Go for it.

Looking forward to the changes. It's great timing with #hackforchange coming up at the end of the month. There's a group getting together locally, and I can talk about your work if you don't mind.

Cheers.

[Chris Skudlarczyk]

Hey all,
Just checking if there are questions on the parking pull request. I'm attaching an example output from the v2 parking api so you can wrap your head around the service response format. It's definitely larger (more fields) than v1. Hoping this helps grokking.

Sorry it's such a big batch of changes.

Hope all is well in Madison and wish I could attend the upcoming #hackforchange.

-Chris

--
You received this message because you are subscribed to the Google Groups "HackingMadison" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hackingmadiso...@googlegroups.com.
To post to this group, send email to hacking...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/bb3f3abb-70d1-403a-8b28-c82498caacf9%40googlegroups.com.

[Chris Skudlarczyk]

Crap, I also noticed that the change in formatting on the City Special Events page also broke the v1 parking API--currently throwing error.

I just now Implemented the same fix I did in v2 to the v1 api and added it to the pull request.

[Greg Tracy]

Sorry Chris. I just haven't allocated hours for it. Even if I don't do something new this weekend, I can start with this pull request at least!

Thanks.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/CAO35DmWH6v%3DQEw-T4sgReiYnbwLhWk15v9gum%3D%3DRtTs4P-pn4Q%40mail.gmail.com.

[Greg Tracy]

It's live!

Awesome work, Chris. Thank you!

[Chris Skudlarczyk]

Thanks Greg! 

On Saturday, May 31, 2014, Greg Tracy <gtr...@gmail.com> wrote:

It's live!

Awesome work, Chris. Thank you!

--
You received this message because you are subscribed to the Google Groups "HackingMadison" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hackingmadiso...@googlegroups.com.
To post to this group, send email to hacking...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hackingmadison/90af517a-47e7-44c1-b901-98c3cd8be1dc%40googlegroups.com.