Last Comment Bug 1003236 - [Meta] Transition BzAPI consumers to the native REST API
: [Meta] Transition BzAPI consumers to the native REST API
Status: NEW
: meta
Product: bugzilla.mozilla.org
Classification: Other
Component: API (show other bugs)
: Production
: All All
-- normal (vote)
: ---
Assigned To: Nobody; OK to take it and work on it
:
:
Mentors:
Depends on: 974363 990765 1302392 1302469 692891 774141 924405 930410 962264 1028709 1302390 1302494 1302580 1309737
Blocks:
  Show dependency treegraph
 
Reported: 2014-04-29 09:14 PDT by Ed Morley [:emorley]
Modified: 2016-10-12 16:40 PDT (History)
11 users (show)
See Also:
Due Date:
QA Whiteboard:
Iteration: ---
Points: ---


Attachments

Description User image Ed Morley [:emorley] 2014-04-29 09:14:57 PDT
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.
Comment 1 User image David Lawrence [:dkl] 2014-04-29 12:42:36 PDT
(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
Comment 2 User image Chris Lonnen :lonnen 2014-06-27 19:21:14 PDT
Any idea when versioning will be added? It would be nice to revisit the affected code once instead of twice.
Comment 3 User image Byron Jones ‹:glob› 2014-06-29 21:45:08 PDT
(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.
Comment 5 User image Emma Humphries ☕️ [:emceeaich] (UTC-8) +needinfo me 2016-09-13 10:14:32 PDT
I'm using https://github.com/search?q=api-dev.bugzilla.mozilla.org&ref=searchresults&type=Code&utf8=%E2%9C%93 to find projects that may be using bzapi.
Comment 6 User image Ed Morley [:emorley] 2016-09-13 10:20:16 PDT
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.
Comment 7 User image Emma Humphries ☕️ [:emceeaich] (UTC-8) +needinfo me 2016-09-13 10:25:54 PDT
(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.
Comment 8 User image Ed Morley [:emorley] 2016-09-13 10:57:50 PDT
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.
Comment 9 User image Mark Côté [:mcote] 2016-09-13 18:02:40 PDT
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.
Comment 10 User image Gervase Markham [:gerv] 2016-09-20 01:07:00 PDT
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
Comment 11 User image Kohei Yoshino [:kohei] 2016-09-20 05:44:45 PDT
AFAIK, Bug 504937 and Bug 994896 should be fixed before EOLing BzAPI.
Comment 12 User image Ed Morley [:emorley] 2016-09-20 06:00:15 PDT
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).
Comment 13 User image Gervase Markham [:gerv] 2016-09-20 06:44:49 PDT
(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
Comment 14 User image Ed Morley [:emorley] 2016-09-20 06:49:49 PDT
(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.
Comment 15 User image Mark Côté [:mcote] 2016-09-20 13:41:59 PDT
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.

Note You need to log in before you can comment on or make changes to this bug.