1159406 - Update to JSON-API 1.0

Status: RESOLVED FIXED

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

Description

[John Whitlock [:jwhitlock]]

What problem would this feature solve?
======================================
The API was designed around JSON-API Release Candidate 2 (rc2), with the assumption that  the final release was soon, and wouldn't be significantly different.  On March 16th, 2015, rc3 was released, with significant changes to rc2.  The specification continues to change

Who has this problem?
=====================
API Client Writers

How do you know that the users identified above have this problem?
==================================================================
Our own tools were easier to write by using third party tools like  ember-json-api-1.0 and drf-json-api.  These tools are expected to update to the new JSON format, and we'll have to stick with old versions that are compatible with rc2.  It will be increasingly difficult to find the rc2 documentation.

How are the users identified above solving this problem now?
============================================================
We're sticking with rc2 and older versions of third party tools.

Do you have any suggestions for solving the problem? Please explain in detail.
==============================================================================
We can change v1 to reflect JSON API rc3 as soon as possible, since it is not being used outside of the project.  Or, we could plan to upgrade the API as part of v2, once we have a working API with good MDN data.

Is there anything else we should know?
======================================
Here's a browser resource in JSON API v1:

https://browsercompat.herokuapp.com/api/v1/browsers/6

{
    "browsers": {
        "id": "6", 
        "slug": "firefox", 
        "name": {
            "en": "Firefox"
        }, 
        "note": null, 
        "links": {
            "history": [
                "20", 
                "6"
            ], 
            "history_current": "20", 
            "versions": [
                "67", 
                "68", 
                "69", 
                "279"
            ]
        }
    }, 
    "links": {
        "browsers.history": {
            "type": "historical_browsers", 
            "href": "https://browsercompat.herokuapp.com/api/v1/historical_browsers/{browsers.history}"
        }, 
        "browsers.history_current": {
            "type": "historical_browsers", 
            "href": "https://browsercompat.herokuapp.com/api/v1/historical_browsers/{browsers.history_current}"
        }, 
        "browsers.versions": {
            "type": "versions", 
            "href": "https://browsercompat.herokuapp.com/api/v1/versions/{browsers.versions}"
        }
    }
}


In the rc3 format, it may look more like:

https://browsercompat.herokuapp.com/api/v1/browsers/6

{
    "data": {
        "type": "browsers",
        "id": "6",
        "slug": "firefox",
        "name": {
            "en": "Firefox"
        },
        "note": null,
        "links": {
            "self": "https://browserscompat.herokuapp.com/api/v1/browsers/6",
            "history": "https://browsercompat.herokuapp.com/api/v1/browsers/6/links/history",
            "history_current": {
                "self": "https://browsercompat.herokuapp.com/api/v1/browsers/6/links/history/current",
                "related": "https://browsercompat.herokuapp.com/api/v1/browsers/6/revert",
                "linkage": {"type": "historicalbrowser", "id": "20" }
            },
            "versions": {
                "self": "https://browsercompat.herokuapp.com/api/v1/browsers/6/links/versions",
                "related": "https://browsercompat.herokuapp.com/api/v1/browsers/6/versions",
                "linkage": [
                    {"type": "versions", "id": "67"},
                    {"type": "versions", "id": "68"},
                    {"type": "versions", "id": "69"},
                    {"type": "versions", "id": "279"}
                ]
            }
        }
    }
}

This would require a rewrite of serializers, already planned in bug 1153288.

Comment 1

[John Whitlock [:jwhitlock]]

JSON API v1.0 has been released, so that should be the target specification.

Comment 2

[MDN Team (:mdn-dev)]

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

https://github.com/mdn/browsercompat/commit/ebe234164ce04bbedcd595dc1584f6e8a5aec929
bug 1159406 - Refactor API path lookup

Because API path lookup will change when v1/v2 APIs are served at the
same time, coordinate API path lookups for tests:

* Add api_reverse method to base TestCase, for generating paths to API
  views.
* Remove reverse method from base TestCase, and add full URL lookups as
  needed in derived classes.

https://github.com/mdn/browsercompat/commit/96bbb7244deb470479b93229180c53865f63b634
bug 1159406 - Namespace the v1 API views

Use the DRF NamespaceVersioning strategy for serving the v1 API.  This
will allow the v2 API to exist alongside the v1 API.

Comment 3

[MDN Team (:mdn-dev)]

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

https://github.com/mdn/browsercompat/commit/3a0d8b5cc59fd332681ac377778dd3ff610100c4
bug 1159406 - Fix importer for namespaced API

The importer includes links to the API when the user can commit data,
and the reverse is broken with namespaced API URLs. This adds a test to
use a privileged user to fetch the view, and fixes the template to use
namespaced API URLs.

https://github.com/mdn/browsercompat/commit/b263247fec1cb6938ac6cee3299170f04431f02c
Merge pull request #86 from mdn/fix_importer_1159406

bug 1159406 - Fix importer for namespaced API

Comment 4

[Jeremie Patonnier :Jeremie]

John, do we have tracking bugs for our BC API V1 and V2?

If not, could you create them and make the bug dependencies?

Comment 5

[John Whitlock [:jwhitlock]]

Added tracking bug 1240757

Comment 6

[MDN Team (:mdn-dev)]

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

https://github.com/mdn/browsercompat/commit/3a12742e794744db245cc65f72ec4cd276ad9153
bug 1159406 - Fix v1 API test, spec by mdn_key

The integration test was:

GET /api/v1/specifications?mdn-key=CSS2.1

and is now:

GET /api/v1/specifications?mdn_key=CSS2.1

Changing from a dash to an underscore makes the filer actually work.

https://github.com/mdn/browsercompat/commit/147db53f1089da4417aa5c029c1215bdc930ef4b
bug 1159406 - Fix v1 API test, section update

Test was updating maturity, which is not a relationship on sections.
Switched to updating the specification.

https://github.com/mdn/browsercompat/commit/cb1d61326742a6d8ec08ca5bd0fb28d14b7166a2
bug 1159406 - Remove unused v1 API test results

These test results were from failed API integration test runs. The .json
equivalents represent the expected responses.

https://github.com/mdn/browsercompat/commit/39519f9323639acf65dc48051267aa252a49df48
bug 1159406 - Move v1-specific classes and tests

To prepare to serve multiple API versions at once:
* Create a new folder for v1-specific code
* Move v1-specific classes (parsers, renderers) into new v1 folder
* Split API classes like viewsets into common and v1-specific classes
* Rearrange tests between general and v1-specific tests

https://github.com/mdn/browsercompat/commit/85132c803f5a902873315e9fccc96b29fc96d154
bug 1159406 - Add v2 API

Mostly working v2 API implementation (JSON API v1.0):

* v2 API parser
* v2 API renderer
* related links (GET the related items to a subject)
* relationships links (GET/PATCH the IDs of related items)
* Server-side viewfeature HTML using v2 API data

Doesn't include:
* Environment-overriding of page_size as used on bcnext
* POST/DELETE to update single members of M2M relationships
* A careful evaluation of all the MUST items of the JSON API spec
* Documentation
* Integration tests
* Tools working against v2 API

https://github.com/mdn/browsercompat/commit/1380130faee30cdfb8cc8b2fe9e9908755893510
Merge pull request #91 from mdn/v2_api_1159406

bug 1159406 - Add v2 api

quick r+ from willkg, but too big for complete review

Comment 7

[MDN Team (:mdn-dev)]

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

https://github.com/mdn/browsercompat/commit/c69622e801031191542d014411de1852561c9053
bug 1159406 - Add v2 integration test framework

Update the tools to run integration tests against both the v1 and v2
APIs, both locally (make test-integration) and in TravisCI. The v1 API
is still used to install the initial test fixtures for v2 API tests.

https://github.com/mdn/browsercompat/commit/a0fe2ccc152cf65b1ef16561a131c6074a48c5ab
bug 1159406 - Add v2 API integration tests

The v2 API integration tests are similar to the v1 API tests, except for
changes in JSON API v1.0:

* PATCH is used instead of PUT to update resources
* Filtering has changed from ?browser=6 to ?filter[browser]=6
* The new related and relationship links are tested

https://github.com/mdn/browsercompat/commit/eff36cb7db6d9c81fce436a3db64294f1e5bdfc8
bug 1159406 - Add v2 API documentation

Include spell check, moving some v1 documents to generic section.

https://github.com/mdn/browsercompat/commit/b4301a1348d8f4efd14ebe712e7d0e8a06d1c521
Merge pull request #92 from mdn/docs_v2_api_1159406

bug 1159406 - Add integration tests and documentation for v2 API

unreviewed - no new functionality, just tests confirming functionality and docs to be reviewed when read by future users

Comment 8

[John Whitlock [:jwhitlock]]

v2 API shipped to https://browsercompat.herokuapp.com/api/v2 . Further changes will be made to both the v1 and v2 APIs. For example, JSON API v1.0 is not fully implemented, and known issues are tracked against bug 1243225.