1242613 - /api should have links to /api/v1 and /api/v2

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: BrowserCompat, defect)

Description

[John Whitlock [:jwhitlock]]

What did you do?
================
1. Go to http://browsercompat.herokuapp.com/api

What happened?
==============
Automatically redirected to /api/v1

What should have happened?
==========================
Given the choice of /api/v1 and /api/v2, with an explanation that v2 is going away

Is there anything else we should know?
======================================

Comment 1

[Anthony Maton [:anthony]]

Do you think something written in javascript to catch if there was a 301 Header and display an informative message, would be a solution ?

If that's not the case, would you have a starting point for me ;)
It's my first time dealing with browsercompta.

Comment 2

[John Whitlock [:jwhitlock]]

This needs to be done in Django/Python:

* Add a new template to webplatformcompat/jinja2/webplatformcompat, such as "api.html", that links to the v1 and v2 APIs, includes a one-line explanation of the differences, and links to the full documentation
* In webplatformcompat/urls.py - Change '^api/$' pattern from a RedirectView to a TemplateView using the new template
* Update the header navigation so "API" goes to this new page instead of the v1 API.

Comment 3

[Anthony Maton [:anthony]]

Note: after a conversation with John, it's in fact the v1 which is going away.

Comment 4

[John Whitlock [:jwhitlock]]

Comment 0 says "an explanation that v2 is going away".  This should say "an explanation that v1 is going away".

The v1 API is based on JSON API RC1, an in-develop version of the specification, now deprecated. The API docs are at http://browsercompat.readthedocs.org/en/latest/v1/intro.html .

The v2 API is based on JSON API v1.0, the current version of the specification. The API docs are at http://browsercompat.readthedocs.org/en/latest/v2/intro.html

The v1 API will be removed when tools using it have been updated to the v2 API.

Comment 5

[MDN Team (:mdn-dev)]

Commits pushed to master at https://github.com/mdn/browsercompat

https://github.com/mdn/browsercompat/commit/67fa414838b5c17a17cf77c6123f8adb8812726c
fix bug 1242613 Add a warning page stating that API in v1 is deprecated an gonna disappear

https://github.com/mdn/browsercompat/commit/3c53351171620228aee69d7b343af164e5899572
bug 1242613 - Change wording on API page

Comment 6

[MDN Team (:mdn-dev)]

Commit pushed to master at https://github.com/mdn/browsercompat

https://github.com/mdn/browsercompat/commit/159a25b97f443444417ab5d94f135a7f18803332
bug 1242613 - Use API endpoints with slashes

Avoid a redirect by using the slash version of the versioned API
entrypoints.