Skip to content

Commit

Permalink
rewrite of OC branch difference docs; updates #463
Browse files Browse the repository at this point in the history
  • Loading branch information
@following5
following5 committed Nov 24, 2018
1 parent 5e516c2 commit d847f6f
Show file tree
Hide file tree
Showing 6 changed files with 112 additions and 60 deletions.
52 changes: 29 additions & 23 deletions okapi/services/caches/geocache/docs.xml
View file
Expand Up @@ -58,15 +58,16 @@
<li><b>description</b> - inserts the OC team annotations into the
description texts,</li>
<li><b>separate</b> (recommended) - includes the <b>oc_team_annotation</b> field
instead.</li>
instead. You are REQUIRED to display its contents alongside with
the owner's cache listing.</li>
</ul>
<p>Please note that you are REQUIRED to display OC team annotations
alongside with the owner's cache listing. In this they differ from
<i>OC team
<a href="%OKAPI:methodargref:services/logs/entry%">log entries</a></i>,
which will only be visible when logs are displayed.</p>
<p>OC team annotations so far are only in use at OCPL-based sites.
OCDE installations will ignore this parameter.</p>
<p>OC team annotations are not to be confused with "OC Team comment"
<a href='%OKAPI:methodargref:services/logs/entry%'>log entries</a>,
which have a similar purpose, but need not to be visible with the cache
description. OC team annotations will be deleted when obsolete, while
the log entries usually will stay.</p>
<p>Note that some OC installations do not implement team annotations. They will
ignore this parameter.</p>
</opt>
<opt name='lpc' default='10'>
Log-entries per cache - the number of logs returned in the <b>latest_logs</b> field.
Expand Down Expand Up @@ -153,7 +154,8 @@
<ul>
<li><b>Own</b>, a moving geocache which is carried by the owner,</li>
<li><b>Podcast</b>, a geocache with attached MP3 file(s). The MP3
data is not accessible via OKAPI.</li>
data is not accessible via OKAPI. This type is only in use
at Opencaching.US.</li>
<li>(Types may be added or removed. Your application MUST be
prepared for any new types and may handle them as "Other".)</li>
</ul>
Expand All @@ -174,8 +176,8 @@
known to be in poor condition, e.g. damaged. Usually there will be further
explanations in the log entries.</p>

<p>Please note that only OCDE-based Opencaching installations provide this
information. ODPL-based sites will always return <b>false</b> here.</p>
<p>Please note that some Opencaching installations don't provide
this information; they will always return <b>false</b>.</p>
</li>
<li><b>url</b> - URL of the cache's web page,</li>
<li>
Expand Down Expand Up @@ -322,11 +324,13 @@
overall rating of the cache, or <b>null</b> when the geocache does not have a
sufficient amount of votes to have a rating.</p>

<p><b>Note:</b> Only OCPL-based Opencaching installations provide ratings for
their geocaches. On OCDE-based installations, this field will always contain
<b>null</b>.</p>
<p><b>Note:</b> Some installations don't provide ratings for
their geocaches; they will always return <b>null</b> for this
field. The <b>has_ratings</b> field of
<a href='%OKAPI:methodargref:services/caches/capabilities%'>services/caches/capabilities</a>
tells if ratings are available.</p>

<p><b>Note:</b> Currently OCPL exposes cache ratings as integers only.
<p><b>Note:</b> Currently OC sites expose cache ratings as integers only.
OKAPI used floats here for forward-compatibility only. In other words, currently
you can get 4.0 or 5.0 here, but not 4.5. This may change in the future though,
without notice.</p>
Expand All @@ -335,16 +339,17 @@
<p>%OKAPI:infotag:ocpl-specific% <b>rating_votes</b> - number of votes submitted
for the rating of this cache.</p>

<p><b>Note:</b> Only OCPL-based Opencaching installations provide ratings for
their geocaches. On OCDE-based installations, this field will always contain
<b>0</b>.</p>
<p><b>Note:</b> Some installations don't provide ratings for their geocaches;
they will always return <b>0</b> for this field. The <b>has_ratings</b> field of
<a href='%OKAPI:methodargref:services/caches/capabilities%'>services/caches/capabilities</a>
tells if ratings are available.</p>
</li>
<li>
<p>%OKAPI:infotag:ocpl-specific% <b>my_rating</b> - float (between 1 and 5),
the rating the user gave for this cache; <b>null</b> if the user did not rate.</p>
<p>This is private data. You will need Level 3 Authentication to access
this field.</p>
<p>See the notices on the <b>rating</b> field.</p>
<p>See the notes on the <b>rating</b> field.</p>
</li>
<li><b>recommendations</b> - number of recommendations for this cache,</li>
<li>
Expand Down Expand Up @@ -414,10 +419,10 @@
</ul>
</li>
<li>
<p>%OKAPI:infotag:ocde-specific% <b>preview_image</b> - On OCDE-based
<p>%OKAPI:infotag:ocde-specific% <b>preview_image</b> - On some
installations, owners may select one of the <b>images</b>
(see above) as a preview image. You are encouraged to display it as a 'teaser'
for this cache. On OCPL-based installations this functionality is disabled and you
for this cache. On other installations this functionality is disabled and you
will always get the <b>null</b> value here.</p>

<p>The value of <b>preview_image</b> is either <b>null</b> or a dictionary describing
Expand All @@ -443,7 +448,8 @@
It will only partially respond to the <b>langpref</b> parameter and may
contain an arbitrary mixture of languages and differently localized data
(<a href='https://github.com/opencaching/okapi/issues/533'>why?</a>).
OCDE installations currently will always return an empty string.</p>
Some installations don't implement OC team annotations; they currently
always return an empty string for this field.</p>
</li>
<li>
<p><b>attribution_note</b> - the proper attribution note for the cache listing according
Expand Down Expand Up @@ -581,7 +587,7 @@
<li>
<b>date_created</b> - date and time (ISO 8601) when the
geocache was listed at the Opencaching site. For OCDE-based installations
this is the date when it was published, while for ODPL installations it is the
this is the date when it was published, while for OCPL installations it is the
date when it was originally submitted. These dates differ if the
geocache is prepared and then published later.
</li>
Expand Down
4 changes: 3 additions & 1 deletion okapi/services/logs/edit/docs.xml
View file
Expand Up @@ -74,7 +74,9 @@
<opt name='rating' default='unchanged' infotags="ocpl-specific">
<p>If the user rated the cache, the option <b>false</b> will withdraw
that rating. Otherwise, it will be ignored (which includes
installations that do not provide geocache ratings).</p>
installations that do not provide geocache ratings; see the
<b>has_ratings</b> field of
<a href='%OKAPI:methodargref:services/caches/capabilities'>services/caches/capabilities</a>).</p>
</opt>
<opt name='langpref' default='en'>
<p>Pipe-separated list of ISO 639-1 language codes. This indicates the
Expand Down
3 changes: 2 additions & 1 deletion okapi/services/logs/entry/docs.xml
View file
Expand Up @@ -157,7 +157,8 @@
state of the geocache listing.
</li>
</ul>
<p>Please note that OCPL-based installations will always return <b>null</b> here.</p>
<p>Please note that some OC installations do not implement this
flag and will always return <b>null</b>.</p>
</li>
<li><b>comment</b> - <a href='%OKAPI:docurl:html%'>HTML string</a>, text entered
with the log entry,
Expand Down
20 changes: 12 additions & 8 deletions okapi/services/logs/submit/docs.xml
View file
Expand Up @@ -95,14 +95,18 @@
<opt name='rating' infotags="ocpl-specific">
<p>An integer in range between 1 and 5 - user's optional rating of a found cache.</p>
<p>Important: <b>logtype</b> has to be "Found it" or "Attended" in order to use
this argument.</p>
<p>Note: You should allow your user to <b>not</b> rate a found cache.</p>
<p>Note: Some OKAPI installations (OCDE codebase) currently do not support
cache ratings. On such installations user's rating will be <b>ignored</b>
(if you include the rating, log entry will be posted successfully, but
rating will be ignored). The <b>can_rate</b> field of
this argument. The rating may be rejected if the user already rated
this cache. You may consult the <b>can_rate</b> field of
<a href="%OKAPI:methodargref:services/logs/capabilities%">services/logs/capabilities</a>
tells if <em>this</em> installation implements rating.</p>
to find out if the rating will be accepted.</p>

<p>Note: You should allow your user to <b>not</b> rate a found cache.</p>
<p>Note: Some OKAPI installations do not support cache ratings. On such
installations user's rating will always be <i>ignored</i> (if you include
the rating, log entry will be posted successfully, but rating will be
ignored). The <b>has_ratings</b> field of
<a href="%OKAPI:methodargref:services/caches/capabilities%">services/caches/capabilities</a>
tells if ratings are avaialble at this installation.</p>
</opt>
<opt name='recommend' default='false'>
<p>Set to <b>true</b> if the user wants to recommend this cache.</p>
Expand Down Expand Up @@ -148,7 +152,7 @@
your user thinks that the cache's condition is fine.</p>

<p>Note: The <b>false</b> option currently is not evaluated by some
installation (OCPL-based sites). They will just ignore it.</p>
installations. They will just ignore it.</p>
</li>
</ul>

Expand Down
3 changes: 2 additions & 1 deletion okapi/static/common.css
View file
Expand Up @@ -20,7 +20,7 @@ body.api { background: #f5f1eb; }

.infotag {
display: inline-block;
background: #d9534f;
background: #5486b2;
color: #fff !important;
font-weight: normal;
font-size: 68%;
Expand Down Expand Up @@ -63,6 +63,7 @@ a.infotag:hover {
.article h1 .subh1 { font-size: 18px; font-weight: normal; color: #888; }
.article h1 .subh1 b { font-weight: normal; color: #944; }
.article h2 { clear: both; margin: 50px 0 10px 0; padding-top: 20px; font-weight: bold; font-style: italic; font-size: 22px; border-top: 2px dotted #aaf; }
.article h3 { clear: both; margin: 20px 0 6px 0; font-weight: bold; font-style: italic; font-size: 18px }
.article p { margin-bottom: 15px; }
.article pre { margin-bottom: 15px; }
.article ul { margin-bottom: 15px; margin-left: 35px; }
Expand Down
90 changes: 64 additions & 26 deletions okapi/views/introduction/introduction.tpl.php
View file
Expand Up @@ -475,40 +475,78 @@
<div class='issue-comments' issue_id='117'></div>


<h2 id='oc-branch-differences'>Differences between OCPL and OCDE branches</h2>
<h2>Differences between Opencaching installations</h2>

<p>Client developers should be aware that the are two primary Opencaching
codebase branches. Some Opencaching installations are running the OCPL branch,
some other are running the OCDE branch. (You can read more about this
<a href='https://github.com/opencaching/opencaching-pl/wiki#brief-introduction-in-english'>here</a>.)</p>
<p>Client developers should be aware that Opencaching sites provide different
sets of features. E.g. Opencaching.US currently does not support OKAPI log
image upload, and there is no geocache rating system at Opencaching.DE.
OKAPI implements several mechanisms that either hide those differences -
you don't need to care about them - or allows your application to automatically
adjust to the Opencaching site's capabilities.</p>

<p>In general, <b>OKAPI supports both of these branches via exactly the same
API interface</b>, so you don't have to worry about the internal differences.
However, you should be aware of the fact, that some things work a bit different
on one branch, than they on the other. (Like, for example, OCDE doesn't have a
cache rating system, so whenever you ask for the <b>rating</b> field of a
geocache, you will get <b>null</b>.)</p>
<h3>OKAPI versions</h3>

<p>In order for you to easily notice methods, parameters and fields which are
specific to only a single of these branches, we display the following "tags" in
many places:</p>
<p>Now and then, new features are added to OKAPI. They will be listed in the
<a href="changelog.html">Changelog</a>, including version numbers. By comparing
those numbers to the installation's current OKAPI version number, as returned by the
<a href='%OKAPI:methodargref:services/apisrv/installation%'>services/apisrv/installation</a>
method, applications can detect if a new feature is available.</p>

<h3 id='site-capabilities'>Site capabilities</h3>

<p>OKAPI methods generally are designed to abstract from differences between OC
installations. E.g. if some geocache or log property is not implemented, OKAPI
will return <i>null</i> or <i>false</i> (as explained in the method docs).
When submitting data, unsupported options are mostly ignored (as documented),
or OKAPI will return an HTTP 200 result with the <i>success</i>=<i>false</i>
field and a user-friendly explanation (as documented).</p>

<p>However, when searching for caches or submitting content, there are a few
exceptions where this can't be done. The docs then will refer to one of the
following methods, that your application can call to find out what features
are available:</p>

<ul>
<li><span class='infotag infotag-ocpl-specific'>OCPL</span> - indicates
that a certain method, parameter or field was designed specificly for
OCPL-based Opencaching sites,</li>
<li><a href='services/attrs/attribute_index.html'>services/attrs/attribute_index</a>
- list of available cache attributes,</li>
<li><a href='services/caches/capabilities.html'>services/caches/capabilities</a>
- geocache capabilities,</li>
<li><a href='services/logs/capabilities.html'>services/logs/capabilities</a>
- logging capabilities, including the submission of cache
recommendations and ratings.</li>
</ul>

<p>This methods also return additional information, that allows to hide
nonfunctional features from user interfaces. E.g. you may want to disable
searching for geocaches by rating, if OKAPI will ignore the user's input
(because the OC site does not implement rating).</p>

<h3></h3>

<h3 id='oc-branch-differences'>Branch tags</h3>

<li><span class='infotag infotag-ocde-specific'>OCDE</span> - indicates
that a certain method, parameter or field was designed specificly for
OCDE-based Opencaching sites.</li>
<p>Throughout the OKAPI documentation, you will encounter options and fields
that are tagged as "OCPL" or "OCDE". These tags have the following meaning:</p>

<ul>
<li>
<span class='infotag infotag-ocde-specific'>OCDE</span> - This feature
currently is only in use at Opencaching sites that are based on the
OCDE software branch (currently Opencaching.DE/IT/FR). If your
application is NOT intended to be used with those sites, you may want
to skip this feature and not implement it.
</li>
<li>
<span class='infotag infotag-ocpl-specific'>OCPL</span> - This feature
currently is only in use at Opencaching sites that are based on the
OCPL software branch (currently Opencaching.PL, NL, US, UK, RO). If
your application is NOT intended to be used with those sites, you
may want to skip this feature and not implement it.
</li>
</ul>

<p>Please note, that <b>you still MAY use all such "marked" methods, parameters
and fields on ALL OKAPI sites.</b> Our methods are designed in such a way that,
even if they are not supported by the underlying Opencaching site, they still
won't throw errors, etc. At worst, they will "fail silently", or return empty
results. All these differences should be described in detail in the
documentation of the affected methods, parameters and fields.</p>
<p>In all other cases, you are recommended to ignore the branch tags. See above
for more information on differences between Opencaching sites.</p>

<p>If you have any questions about this, then ask them
<a href="https://github.com/opencaching/okapi/issues/463">here</a>.</p>
Expand Down

0 comments on commit d847f6f

Please sign in to comment.