Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wrygiel opened this issue Apr 25, 2017 · 8 comments
Closed

Comments

@wrygiel
Copy link
Member

wrygiel commented Apr 25, 2017

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
Copy link
Member Author

wrygiel commented Apr 25, 2017

Summary of changes

In the services/apiref/method method new fields will be added:

image

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:

image

If a method is tagged, then they will also be displayed in the menus:

image

When clicked, the reader will be sent to a new chapter in the introduction which will explain what these tags mean.

@wrygiel
Copy link
Member Author

wrygiel commented Apr 25, 2017

@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
Copy link
Member

kojoty commented Apr 26, 2017

@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 following5 reopened this Nov 1, 2018
@following5
Copy link
Contributor

following5 commented Nov 1, 2018

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

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

@following5
Copy link
Contributor

  • 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants