If there are external uses of the URI-based API, then it should probably be considered an API, with "versioning" and breaking change policies.

Seeing it that way would likely have made the transition more explicit and visible:

• A public "breaking change" notification, with a schedule and deprecation period.
• A temporary support for channel=master where using it shows a warning banner on the page, maybe or maybe not with a HTTP redirect (say to same URI with channel=masterchanged tochannel=main&deprecation=master-channel`, or something, which could use that URI to trigger showing the warning).
  That could then allow automatic testing of URIs at the Flutter end, checking if the URIs they expose do not get a "permanent redirect" HTTP response, which would be a signal to update the URIs.

Since there is only one implementation, "versioning" isn't really the correct word. The version you get is the version that is live today. But explicit breaking changes, with public schedules and deprecations, can still work.

To note, in relation to this specific case, I think we intended to keep master working for the API docs, but missed this case. fb56528 fixes this.

For large changes, I generally verify they don't cause issues for the Flutter API docs locally, but that's not super sustainable. Perhaps we can require a more explicit consideration.

I'm going to close this for now, since we are aliasing master to main.

DartPad doesn't have a huge API surface, we support a handful of query parameters for the Gist ID, the theme, and the UI mode (mobile or desktop). We should probably document that better in the embedding guide.

I can't think of a way for DartPad to integrate with our documentation tooling to say whether or not a snippet still compiles and runs, but I'm happy to discuss any ideas anyone might have to solve that.