V3 API: "/shapes" accepts "include" without validating it, unlike other endpoints

[Redeem Grimm]

Hi all,

I built a trip planner on the V3 API that was used by visitors coming to Boston for the 2026 World Cup matches at Boston Stadium (https://matchachusetts.up.railway.app/) and ran into something on /shapes that I think is worth raising, because the failure is silent rather than loud.

/shapes accepts any include value and returns 200. Every other endpoint I tested rejects an unrecognized include:

/stops?filter[route]=Red&include=banana     -> 400
/trips?filter[route]=Red&include=banana     -> 400
/vehicles?filter[route]=Red&include=banana  -> 400
/shapes?filter[route]=Red&include=banana    -> 200

This holds on every supported value of MBTA-Version, from 2017-11-28 through 2021-01-09. /shapes also never returns an included member, on any version, so as far as I can tell include has never done anything on this endpoint.

Why it matters in practice. The swagger docs describe filter[route] on `/shapes` as filtering by /data/{index}/relationships/route/data/id. On 2020-05-01 and later, shape resources carry no relationships member at all, so that pointer cannot resolve. The natural thing to try is one request with filter[route]=Red,Orange,...&include=route, read relationships.route.data.id off each shape, and colour each polyline accordingly.

That request returns 200 with a flat list of shapes, no relationships, and no `included`. Because it succeeds, the reasonable first conclusion is that your own query is wrong rather than that the endpoint does not support what the docs describe. A 400 would have made it obvious in one request.

For anyone hitting the same thing: on the current default version there is no route attribution in a `/shapes` payload, so you need one request per route and you take the route identity from the request rather than the response. On `2019-07-01` and earlier the relationship is still emitted, so a single multi-route call still works and also gives you back `priority`, which is the field that identifies a route's representative shape.

The documentation half I have sent as a PR against "mbta/api", since issues are disabled there: https://github.com/mbta/api/pull/1066. It just replaces the stale pointer text with an accurate description of what the filter accepts.

The validation half is a question rather than a patch, which is why I am asking here:

1. Is "/shapes" intentionally exempt from include validation, or is that a side effect of the controller not declaring any includes?
2. If a 400 would be welcome, it is a breaking change for anyone currently passing "include" to "/shapes" and quietly getting a 200. Would that need to go behind a new "MBTA-Version", the way the "2020-05-01" shape changes were handled?

Happy to put up a PR for the validation change too if there is a shape it should take.

Thanks,
Redeem Grimm