fix: align routes-for-agency with OBA API spec

[reddy-santhu]

Closes #845

This PR addresses the behavioural gaps identified in the spec for GET /api/where/routes-for-agency/{id}, verified against the live Puget Sound OBA server.

Changes

Handler

• Unknown agency now returns 404. Previously the handler called sendNull which produced a 200 response with a null body. The fix replaces it with sendNotFound, consistent with how stops, routes and trips handle the same case.
• Pagination removed. The spec states the full route list is always returned and limitExceeded is always false. The ParsePaginationParams and PaginateSlice calls are dropped and limitExceeded is hardcoded to false.
• includeReferences=false supported. When passed, the references block is returned empty. Defaults to true.

Models

• Optional route fields (shortName, longName, description, url, color, textColor) now use omitempty so they are absent from the response when the GTFS feed does not supply them, matching the spec's field definitions.
• nullSafeShortName is removed from the wire format with json:"-". It is an internal Java implementation detail that was leaking into responses and is not part of the spec schema.
• Optional AgencyReference fields (lang, phone, email, fareUrl, disclaimer) now use omitempty. Required fields (id, name, url, timezone, privateService) are unchanged.

Cleanup

• Removed dead NullSafeShortName assignments in reference_utils.go and trip_details_handler.go. The field is json:"-" so those values were never serialised or read anywhere.

Tests

• TestRoutesForAgencyHandlerEndToEnd extended with per-route assertions on required fields (id, agencyId, type) and per-agency assertions on required reference fields (id, name, url, timezone, privateService), and a check that nullSafeShortName is absent from every route object.
• TestRoutesForAgencyHandlerNonExistentAgency updated to assert 404 with "resource not found" text.
• TestRoutesForAgencyHandlerLimitExceededAlwaysFalse replaces the old pagination test.
• TestRoutesForAgencyHandlerIncludeReferencesFalse added for the includeReferences=false path.
• TestAgenciesWithCoverageHandlerEndToEnd, TestRouteHandlerEndToEnd, TestRouteWithNilValuesJSON updated for the new omitempty serialisation behaviour.

Verification

Envelope and list shape (Maglev)

{
  "version": 2,
  "code": 200,
  "text": "OK",
  "limitExceeded": false,
  "routeCount": 8,
  "agencyRefCount": 1
}

Route fields — side by side
Live OBA Java server:

{
  "agencyId": "40",
  "color": "2B376E",
  "description": "",
  "id": "40_532",
  "longName": "Everett - Bellevue",
  "nullSafeShortName": "532",
  "shortName": "532",
  "textColor": "FFFFFF",
  "type": 3,
  "url": "https://www.soundtransit.org/ride-with-us/routes-schedules/532"
}

Maglev after this PR:

{
  "agencyId": "40",
  "color": "FFB819",
  "id": "40_1-SHUTTLE",
  "longName": "Link Replacement Shuttle Bus",
  "shortName": "Shuttle",
  "textColor": "000000",
  "type": 3
}

nullSafeShortName is gone. description and url are absent rather than serialised as "" when the GTFS feed does not supply them.

Agency reference (Maglev)

{
  "email": "main@soundtransit.org",
  "fareUrl": "https://www.soundtransit.org/ride-with-us/how-to-pay/fares",
  "id": "40",
  "lang": "en",
  "name": "Sound Transit",
  "phone": "1-888-889-6368",
  "privateService": false,
  "timezone": "America/Los_Angeles",
  "url": "https://www.soundtransit.org"
}

includeReferences=false (Maglev)

{
  "agencies": [],
  "routes": [],
  "situations": [],
  "stopTimes": [],
  "stops": [],
  "trips": []
}

Unknown agency — defect fixed
Live OBA Java returns a malformed error envelope with no standard fields:

{ "code": null, "text": null }

Maglev returns a proper 404:

{ "code": 404, "text": "resource not found" }

Auth and validation

Scenario	Code	Text
Invalid API key	401	permission denied
Malformed ID (11@10)	400	id contains invalid characters

Notes

The version query parameter is not validated by this PR. Supplying a value other than 2 returning 500 is documented in the spec but per-handler version checking would be inconsistent with the rest of the codebase. If needed, it belongs in shared middleware.

[reddy-santhu]

Hey @aaronbrethorst, would you mind taking a look at this when you get a chance? I want to make sure I'm heading in the right direction before picking up more issues , thanks!