Document error for obsolete API version

[ckarlof]

This will allow us to rev our API and retire old versions without breaking older native clients in indecipherable ways (as long as they handle this error!).

[rfk]

Some additional context in https://bugzilla.mozilla.org/show_bug.cgi?id=951306

[ckarlof]

I propose "410 Gone" for an obsolete API endpoint.

[dannycoates]

Is there a specific reason we can't just use 404? Otherwise we need to keep track of obsolete routes instead of just deleting them.

[ckarlof]

I'm fine with 404.

[warner]

As we talked about in person, I'm nervous about using 404 for this, because a variety of transient problems (server downtime, DNS failures, client-side network borkage) could provoke the client to tell our user "you need to upgrade your browser" instead of "please try again later". Confusing and annoying. So I'd be a lot happier with something like 410 Gone along with a URL that lists the currently relevant API versions and known-new-enough client versions.

It does mean we have to keep something for v1 around forever, but I'm hoping that it can be a single wildcard-route for anything that starts with /v1/, and the long-term cost will be like three lines per removed API version.

[warner]

So the proposal is:

410 Gone, error="Obsolete API", URL= pointer to a page with upgrade instructions

[ckarlof]

+1 to 410.

[ncalexan]

+1 to 410. Stick a fork in it.

[ncalexan]

Can we please clarify exactly which endpoints this is for? Issue suggests just /v1/auth/password, but this is generally useful.

[ckarlof]

Yes, I intended this error could be returned by any API call.

[dannycoates]

You can now test the behavior against master with any url starting with /v0/

[ckarlof]

yay, closing.