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

Open
wrygiel opened this Issue Apr 25, 2017 · 7 comments

Comments

Projects
None yet
3 participants
@wrygiel
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

This comment has been minimized.

Member

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

This comment has been minimized.

Member

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

following5 commented Nov 3, 2018

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

This comment has been minimized.

Contributor

following5 commented Nov 10, 2018

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

This comment has been minimized.

Contributor

following5 commented Nov 11, 2018

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

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