The current ReST API (i.e. /opennms/rest or /opennms/api/v1) is the official API.
There is some work on /optnnms/api/v2 for some endpoints, but lots of them are missing.
There are some features that don't have a v1 alternative, and only provide v2 alternative. This is fine, but as v2 is not documented and/or completed, but it seems reasonable to provide an implementation for the missing endpoints, just to be able to have v2 as an alternative of v1.
The best feature of the v2 API, is the ability to specify powerful filters using FIQL. This by itself is enough reason to have a v1 alternative to be able to implement reach interfaces that can have filters as powerful as the filters you can currently use on the OpenNMS WebUI, and even have the ability to make more powerful filters.
Another feature of FIQL in Apache CXF is the ability to create aliases. This is not used at the moment, but could provide human readable alternatives for some attributes, in order to define filters using the same names you see on the JSON/XML output, instead of defining the filters as HQL expects them (which is how the current implementation works not only on v2 but also on v1).
Here is the list of the currently available endpoints in v2:
Here is the list of the missing endpoints (exist on v1 but not on v2 that can benefit from FIQL):
Note: I'm not 100% sure if the last 3 requires a v2 implementation.
Here is the list of v1 end-points that may not have v2 counterparts, because those are not expected to have filtering capabilities (at the moment):