Finalize and document stop and trip problem reporting API

[bdferris]

OneBusAway has long supported a mechanism for submitting user-generated error reports for both trips and stops through the REST API. I'd like to finalize that API and document it so that it might be used by others. I'm slightly tweaking the format of the API and data, getting rid of the JSON-serialized "data" field and adding a simpler "code" field that actually captures how the API is used in practice. Backwards compatibility will need to be maintained for the existing iPhone app.

[paulcwatts]

Awesome! Looking forward to adding it to the Android app.
On Jun 26, 2012 2:39 PM, "Brian Ferris" <
reply@reply.github.com>
wrote:

OneBusAway has long supported a mechanism for submitting user-generated
error reports for both trips and stops through the REST API. I'd like to
finalize that API and document it so that it might be used by others. I'm
slightly tweaking the format of the API and data, getting rid of the
JSON-serialized "data" field and adding a simpler "code" field that
actually captures how the API is used in practice. Backwards compatibility
will need to be maintained for the existing iPhone app.

---

Reply to this email directly or view it on GitHub:
#18

[bdferris]

Key documentation:

http://developer.onebusaway.org/modules/onebusaway-application-modules/current-SNAPSHOT/api/where/methods/report-problem-with-stop.html
http://developer.onebusaway.org/modules/onebusaway-application-modules/current-SNAPSHOT/api/where/methods/report-problem-with-trip.html

NOTE: The current API at http://api.onebusaway.org/ supports a slightly different version of the API at the moment. I will try to push an update this week that will bring it inline with what's documented here. Stay tuned.

[barbeau]

@bdferris Brian - is this API and the corresponding admin console to retrieve the stop/trip problem reports considered complete? I'm having an issue (Issue #23) retrieving the stop problem reports from the onebusaway-webapp admin console.

[barbeau]

Just to document some of the conversations we've had lately surrounding this issue and issue #23 - it looks like #23 is only a web interface issue and can be resolved with a few simple jsp code edits.

It seems that the issue surrounding the Android app's inability to submit trip/problem reports is caused by the new version of the Trip/Problem Report API (i.e., this issue), which doesn't seem to be working (perhaps that is why its still open??).

Paul currently plans to revert Android app to old Trip/Problem Report API, which has been confirmed by me (using OBA Tampa) and him (using OBA Puget Sound) to work.

Excerpts of an email chain with Paul:

---

Apparently trip/stop problem reporting has been broken in Android since I don't know how long ago -- apparently it broke in Android and I had only been made aware this week. So I did some digging and I found the initial cause, although I don't know the root cause.

First, some history:

The iPhone app and the Android app use different REST endpoints to report stop and trip problems. Brian's initial implementation was an undocumented addition to the API at the endpoint:

/api/where/report-problem-with-trip.json

Back in July 2012 when I was asked to implement problem reporting in Android, I first needed to have the API documented before I could use it, and Brian documented a new endpoint with a slightly updated API:

/api/where/report-problem-with-trip/<trip_id>.json

That's here: #18

So the reason why Android problem reporting broke is this:

1. The iPhone app continues to use the old API;
2. The Android app uses the new API;
3. Somewhere in the past 7 months, the new API broke.

I can change the Android app to use old endpoint/API and the reports get saved to the Puget Sound DB without an issue. It's only when I use the newer, documented API endpoint they don't seem to get saved.

Why is this? What is the root cause? I don't know. Some guesses could be:

1. There was a regression in the code that broke the new endpoint;
2. The Puget Sound instance somehow is running an older version of the server;
3. ??? Something else? I'm not sure.

---

OK after doing a deeper dive, I'm still coming up empty. I'm actually now confused as to how the Puget Sound installation ever worked. I can't seem to see how it ever worked using any version of the code that is in GitHub -- there just never was a server method that handled that endpoint.
...
I think at this point I'm leaning toward fixing the bug on the Android side, and modifying the documentation to document what actually works.

[barbeau]

Android app has now been reverted to use old stop/trip problem reporting API endpoints, and this has been pushed out as an app update:
OneBusAway/onebusaway-android@060676a

[barbeau]

This issue is documented as fixed in v1.1.0 release (http://developer.onebusaway.org/modules/onebusaway-application-modules/current/release-notes.html), so I'm going to close this issue and open a new one referencing this issue saying that apparently the new API endpoint isn't working properly.

[barbeau]

Actually, looking at another issue, at the time of Paul's testing Puget Sound was running a version older than v1.1.0, so it wouldn't have had the new API endpoint active. I'm going to leave this as-is without any new issues until we have a chance to test the new endpoint with a v1.1.0 or higher OBA server (an aside - as of two months ago GA Tech was running 1.1.8-SNAPSHOT - http://atlanta.onebusaway.org/).