Join GitHub today
Additional visual cues for marking OCPL-specific or OCDE-specific features #463
There are already a number of features which work "only on OCPL" or "only on OCDE". Of course they don't throw exceptions when run outside of OCPL/OCDE, they just return empty results, etc.
The sad fact is that the number of these features will be growing. There are some features which both OCPL and/or OCDE developers would like OKAPI to support, but the other OC-branch simply doesn't implement them. In the near future we expect some new methods to be included in OKAPI which will return non-empty results only in OCPL-branch.
However, this is "too much". We cannot expect the external developer to read through all the details of each method in order to learn that this method will return empty results in "his favorite" OC site. We need some clear visual cues in the OKAPI documentation pages which will inform all the readers about this.
This also means that we need to inform them a bit more about the fact of existing OCPL and OCDE branches.
Summary of changes
In the services/apiref/method method new fields will be added:
Every method and parameter will now be allowed to "mark itself" with one of these tags. The OKAPI page will display such tags in various places, for example:
If a method is tagged, then they will also be displayed in the menus:
When clicked, the reader will be sent to a new chapter in the introduction which will explain what these tags mean.
I am not happy with this documentation change, because it encourages developers to write apps that work properly only on one branch. Or to implement features just for one branch, which will not be available at the other branch if it adds those features later. (And to guess branches from site URLs... which of course could be avoided by adding a way to retrieve the branch ID.)
Wouldn't it be better to have individual flags in apisrv/installation, which tell if a feature is available or just a dummy?