Additional visual cues for marking OCPL-specific or OCDE-specific features

[wrygiel]

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.

[wrygiel]

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.

[wrygiel]

@kojoty, your methods won't have to be in a separate "ocpl" directory after this change. You will be able to marked them as "ocpl-specific" and put them on any path.

[kojoty]

@kojoty, your methods won't have to be in a separate "ocpl" directory after this change. You will be able to marked them as "ocpl-specific" and put them on any path.

cool, I'll chanage the path in next commits

[following5]

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?

[following5]

Wouldn't it be better to have individual flags in apisrv/installation, which tell if a feature is available or just a dummy?

... as suggested in #398.

[following5]

Those OCDE/OCPL tags also are incomplete, because they don't cover many details. E.g. if an owner may submit "Found it" for own caches.

We can implement #398 first and then see what to do with the OCDE/OCPL tags.

[following5]

Another shortfall is that some "OCPL" parameters and fields are not available yet at Opencaching.US. So developers cannot rely on it.

[following5]

• New methods services/caches/capabilities and services/logs/capabilites allow developers to query installation-dependent features.
• Completely rewritten the docs on OC site differences and branch tags. The documented purpose of branch tags now is to know which features not need to be implemented, if a client is only written for special OC sites. For all other purposes, the branch tags are declared obsolete (though they are useful for OKAPI development!)
• Changed color of branch tags from warning-red to a dark "OC blue". An alternative would be brown.
• Removed most of the other (redundant) references to OCDE and OCPL branches from method docs. Where developers need to know about installation differences, docs now refer to the capabilities methods.

I am ok with this now. If anyone - especially wrygiel - is not happy with those changes, please reopen.