Open Bug 1003236 Opened 10 years ago Updated 5 years ago

[Meta] Transition BzAPI consumers to the native REST API

Categories

(bugzilla.mozilla.org :: API, task)

Product:
bugzilla.mozilla.org
Component:
API
Version:
Production
Type:
task
Priority:
Not set
Severity:
normal

Tracking

()

People

(Reporter: emorley, Unassigned)

References

(Depends on 3 open bugs)

Details

(Keywords: meta) 

The BzAPI shim will mean existing BzAPI consumers should keep working for the foreseeable future (presuming we're now intending on supporting it for some time), but I'm presuming we'll still want to encourage projects to switch to the new API where possible - if only since new feature will not be made available via the BzAPI shim.

This bug is for tracking the efforts of people switching to the native API, both for future decisions as to whether it's viable to depreciate the shim, and also in case example switch-overs are useful to other consumers.
Summary: [Meta] Transitioning BzAPI consumers to the native REST API → [Meta] Transition BzAPI consumers to the native REST API
Depends on: 974363, 924405, 930410, 990765
Depends on: 692891, 962264
Depends on: 774141
(In reply to Ed Morley [:edmorley UTC+0] from comment #0)
> The BzAPI shim will mean existing BzAPI consumers should keep working for
> the foreseeable future (presuming we're now intending on supporting it for
> some time), but I'm presuming we'll still want to encourage projects to
> switch to the new API where possible - if only since new feature will not be
> made available via the BzAPI shim.
> 
> This bug is for tracking the efforts of people switching to the native API,
> both for future decisions as to whether it's viable to depreciate the shim,
> and also in case example switch-overs are useful to other consumers.

This is true. We do not plan to support the BzAPI extension from now on and it will
only get critical fixes. The native REST API is the preferred method and we will
be adding enhancements and versioning to it in the future.

dkl
Any idea when versioning will be added? It would be nice to revisit the affected code once instead of twice.
(In reply to Chris Lonnen :lonnen from comment #2)
> Any idea when versioning will be added? It would be nice to revisit the
> affected code once instead of twice.

versioning of the current API isn't planned.

we will ensure that any changes will not break existing clients -- we may add new fields/params but existing fields/params will not change.

we are aiming to have a new versioned REST API designed before the end of this year which builds on lessons learnt from bzapi, bugzilla's native api, and community feedback.
Depends on: 1028709
Depends on: 1302390
Depends on: 1302392
Depends on: 1302469
Yeah I was using something similar - GitHub code search is awesome :-)

The URLs that we'll have to check for are:

https://api-dev.bugzilla.mozilla.org/latest/
https://api-dev.bugzilla.mozilla.org/1.3/
https://api-dev.bugzilla.mozilla.org/1.2/
https://bugzilla.mozilla.org/bzapi/

(These all map to the same place, see: https://github.com/mozilla-bteam/bmo/blob/98c3e61041c042f297c669fa52e7d58cf26fb293/.htaccess#L93-L94)

I found a significant proportion of the projects that showed up on GitHub hadn't been touched for several years, and didn't appear to be in use.

The easiest way to know which projects to prioritise (for either us opening PRs against them, or just pestering them) is to review the access logs for:
* User agent (won't be useful in many cases)
* Referrer
* Query parameters (combined with GitHub code search is actually fairly helpful in finding who is making them)

For authenticated requests we can also use the API key and/or usernames.
(In reply to Ed Morley [:emorley] from comment #6)

> The easiest way to know which projects to prioritise (for either us opening
> PRs against them, or just pestering them) is to review the access logs for:
> * User agent (won't be useful in many cases)
> * Referrer
> * Query parameters (combined with GitHub code search is actually fairly
> helpful in finding who is making them)
> 
> For authenticated requests we can also use the API key and/or usernames.

If we need to notify more projects than the ones you mentioned above, then the task of id'ing these other projects should be a bug blocking this one.
Depends on: 1302494
Some additions:

https://github.com/mozilla/git-bz-moz (will need updating once upstream bzexport switched from bzapi)
bug 1302494

(In reply to Ed Morley [:emorley] from comment #4)
> In addition, once there is a native REST API equivalent of
> /bzapi/configuration , bz.js can be updated to use that (bug 974363). We'll
> then need to get all projects to update to the latest release of bz.js.

The list of projects using bz.js is fairly extensive, but includes bugzilla-todos, fileit, bugsahoy, arewee10syet.
Depends on: 1302580
I'd like to have it on record that we're going to EOL bzapi.  Specifically, what's the cost of keeping it going?  I don't like keeping old things around longer than necessary, but neither do I want to deprecate something for no particular reason.  I'm fine either way, but I'd like the rationale recorded. :)

If we definitely do want to remove it at some point, I think here is a good place to decide exactly when as well.
Flags: needinfo?(dylan)
Flags: needinfo?(dkl)
IMO, you should only EOL it when the replacement (built-in) API is of equivalent functionality (or perhaps when the differences are only in bits no-one uses, although you'd have to measure that). Is that yet true?

Gerv
AFAIK, Bug 504937 and Bug 994896 should be fixed before EOLing BzAPI.
Part of deciding EOL will definitely be deciding what the criteria are for it (in terms of amount of notice given, percentage of people switched, feature comparison and so on).

However I think that having a blanket policy of insisting that every feature is ported (rather than on a case by case basis) is counter-productive.

At Mozilla we're typically very bad at switching things off and/or de-supporting 'special snowflake' use-cases (other examples: version control systems + tools, the firefox buildsystems etc). If there are alternative ways for people to achieve the same task, for rarely (or never) used features, then we shouldn't necessarily block on adding that feature to the native API (in addition to the developer time required, feature bloat can be unhelpful).
(In reply to Ed Morley [:emorley] from comment #12)
> However I think that having a blanket policy of insisting that every feature
> is ported (rather than on a case by case basis) is counter-productive.

Well, if features which are used are not ported, you as basically saying "to save me some trouble, you have to rewrite your code". That's not always the wrong thing, but we should recognise that we are not saving the _organization_ time in such a circumstance.

Gerv
(In reply to Gervase Markham [:gerv] from comment #13)
>  but we should recognise that we are not saving the _organization_ time in such a circumstance.

This is not always true. Moving from one feature to another may be faster than adding a new feature to Bugzilla. In addition, the other team may be less resource constrained than the BMO one (or may even be for a use-case that isn't actually worth Mozilla time).

As I said, the decision should be made on a case-by-case basis.
Talking this over with the BMO team again, there appears to be no pressing need to EOL BzAPI.  Dylan fixed the particularly egregious performance problem, and we're going to move it over to its own webhead (we are actually going to try moving all REST/XMLRPC/JSONRPC API calls there, as an experiment).  As we decided some time ago, there will be no new features added to BzAPI, and the ongoing maintenance cost is essentially 0.  This gives us some time to implement the calls mentioned in comment 11, which are generally useful.

At some point we plan to remove XMLRPC and JSONRPC and redo REST so it is standalone (it's currently a wrapper around JSONRPC).  This will be a good time to EOL BzAPI, since it would also require work to rebase it.  However given current priorities I can't see that happening before mid 2017.  So until then people can keep using BzAPI unless we discover other problems.
Flags: needinfo?(dylan)
Flags: needinfo?(dkl)
Depends on: 1309737
Type: defect → task
You need to log in before you can comment on or make changes to this bug.