OKAPI Project - API for OpenCaching sites

Ideas and plans to talk about
wrygiel

BTW, I got some emails about developers wanting to start using OKAPI. I will have to start "fixating" methods soon. This is the proper time for you guys to add comments on method signatures and output formats. We won't be able to change these after people start using them. (We WILL be able to deprecate them and add new methods, but it's not the same - deprecated method will still have to be documented and will clutter the documentation pages.)

By "fixating" methods, I mean "acknowledging that they will be permanently backwards-compatible from now on".

For example, what do you think about "cache_wpt" parameter name (many methods require it), wouldn't it be "prettier" to call it "cachecode" or "ucid" (universal cache ID) or something? (I like such reference-entities to end with "id" or "code".)
wrygiel

I just saw that Google Code has a nice "commenting" feature. While browsing repository (revisions or revision diffs), you may double click a line of code to add a comment, then click "publish your comments" to make it visible to other developers. Seems useful. http://code.google.com/p/opencaching-api/source/browse/trunk/okapi/services/caches/geocache.xml?r=59
Benutzeravatar
mic@
Vereinsmitglied
Vereinsmitglied
Beiträge: 6623
Registriert: 04.12.2009, 00:31

[quote="wrygie"]Sure, you may advertize it. ;) [/quote]

OK, the posting is online
http://www.geoclub.de/viewtopic.php?f=127&t=57763
and here is some sniplet of comment, which You might find useful:

original:
...auch wenn ich bei der bbox statt SWNE doch WSEN bevorzugt hätte
sowie statt "|" ein schlichtes "," als trenner, da es dann identisch zur OSM xapi wäre.


translation:
...although I would have used WSEN instead of SWNE and
a simple "," instead of "|" as delimiter, so that it is identical to OSM xapi.
oliver

[quote="wrygiel"]For example, what do you think about "cache_wpt" parameter name (many methods require it), wouldn't it be "prettier" to call it "cachecode" or "ucid" (universal cache ID) or something? (I like such reference-entities to end with "id" or "code".)[/quote]

Each cache has the following unique identifiers:
id - autoincrement id generated by mysql. Only valid for the specific node
uuid - GUID generated by mysql. There will only be one cache in the entire OC network with that id
wp_oc - waypoint within the OC network

I prefer this way (VB.NET):

Enum CacheIdType
  Id
  Uuid
  WpOc
End Enum

Class CacheId
  Public Id As String
  Public Type As CacheIdType

  Sub New(id As String, type As CacheIdType)
    Me.Id = id
    Me.Type = type
  End Sub
End Class

Function GetCacheInfo(ByVal id As CacheId) As CacheInfo

Client can simply use the function in this way:

info = Server->GetCacheInfo(new CacheId(4711, Uuid))
wrygiel

I think you misunderstood my question. I am only talking about a public NAME for the attribute, NOT THE SOURCE. The source is already decided - waypoint code.

Id is not unique, it should be kept hidden.
Uuid - I don't understand it's function. Who uses it and why? It also should be kept hidden.
waypoint - it's short and globally unique, the only valid option for a cache identifier. Opencaching.com uses it too.
sp2ong

[quote="wrygiel"]

> However, as i have written, it is required to implement some
> modifications to meet the requirements of the new code. E.g. we have
> a cache status "locked, invisible". Not allowed to be viewed by
> users (only admins and owner), no logs allowed, status changes only
> allowed by admin.

[/quote]

In our cache_status we have

(1, 'Gotowa do szukania', 'Ready for search'),
(2, 'Tymczasowo niedostępna', 'Temporarily unavailable'),
(3, 'Zarchiwizowana', 'Archived'),
(4, 'Ukryta do czasu weryfikacji', 'Hidden by approvers to check'),
(5, 'Jeszcze niedostępna', 'Not yet available'),
(6, 'Zablokowana przez COG', 'Blocked by OC Team');

where status 4 is used to caches when are in query to approval by OC Team and nobody only owner and OC Team see this cache and discus with owner cache to make suggested changes to cache. Status 6 is status for blocked by OC Team and is cache is visible by owner and OC Tema but only OC Team can change status and after this owner can do more on own cache but any users can not see this cache
oliver

[quote="wrygiel"]Id is not unique, it should be kept hidden.
Uuid - I don't understand it's function. Who uses it and why? It also should be kept hidden.
waypoint - it's short and globally unique, the only valid option for a cache identifier. Opencaching.com uses it too.
[/quote]

For caches,you are correct. There we may not need uuid. But we have other objects in the database like user, cache_logs, picuture. Each object can be identified by its uuid (universal unique id - its the ucid you suggested). When we use the uuid for other objects, it would be good to have this option for caches, too. Each node already has the uuid.

Waypoint may be initialized with NULL. If the code is not able to assign a waypoint with cache creation, the wp_oc is NULL and will be assigned later by a cronjob. This is a realy rare situation, but it may happen in error situations. Or it may happen when you create a cache, but publish it later. Also not, that the uuid of an object will never, never, never change. Its used for replication in OC network. The waypoint could be changed by the admin - maybe to honor a special user, he gets the waypoint OC1000 assigned manually. I never use primary keys with busniess meaning.

The local id of a cache was required as primary key, because doing sql-joins on uuid is very slow. You are right, Id may be a bad decision for the API and because we have other performance constraints, its not required.

So, my final statement: The API shoud use the caches.uuid as query parameter and give the developer the decision to use optionally caches.wp_oc where required. If have done good experience in my company with the id-class-parameter as explained in the last posting.- if you use it: great. If not ... no problem for me.
sp2ong

Hm, I am not sure that what we want to exchange between OC Nodes use API. I think that it will better to keep individual changes between OC Nodes like different type of cache etc. One of main task is at current is How to users form others Nodes can write logs on other OC Sites without create new account. If I want find cache in Germany I can see on my cache maps on OC PL cahces located in Germany and when click on icon on map I can see properites cache on OC DE. When I found this cache I want to write log to this cache I must do this on OC DE but I want use my userrname sp2ong from OC PL and I don't want create account on OC DE fro make log. OC DE can verify my account on OC PL (maybe by API OAuth) OK I enter log  on OC DE and one thning what users need to have information about found, not found ??? in my OC PL profile for own statistics. Maybe API can get this info from OC DE to OC PL sql table cache_ocnodes (it is table to store base information about caches founde ?? by local users on other OC Nodes to create information in user profile. It is simple and we can not exchange many information between OC NOdes and this allow to have OC US own cache types, similar OC PL and OC DE. If OC PL user want create cache located in Germany must do this on OC DE becasue users must agree with local rules OC DE Node. For this reason OC PL can not create cache located outside  own country becasue we are decide that OC PL is local Geocaching services for polish users localed in Poland but at current OC PL users can register cache on OC PL located any country but it maybe better we can cahnge this like on OC US where during register cache user can select only Canada, US, Mexico.
oliver

[quote="sp2ong"]In our cache_status we have (...)[/quote]

Okay, thank you for explanation.
The differences are in id 6 and 7.
We dont use 4 in oc.de (however, it may be the same as id 7).

For future flexibility, the OKAPI code should not rely on the id's.

Code: Alles auswählen

SET NAMES 'utf8';
DROP TABLE IF EXISTS `cache_status`;
CREATE TABLE `cache_status` (
  `id` tinyint(3) unsigned NOT NULL auto_increment,
  `name` varchar(80) NOT NULL,
  `trans_id` int(10) unsigned NOT NULL,
  `de` varchar(60) NOT NULL COMMENT 'obsolete',
  `en` varchar(60) NOT NULL COMMENT 'obsolete',
  `allow_user_view` tinyint(1) NOT NULL,
  `allow_owner_edit_status` tinyint(1) NOT NULL,
  `allow_user_log` tinyint(1) NOT NULL,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `name` (`name`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='static content' ;

INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('1', 'Ready for search', '531', 'Kann gesucht werden', 'Ready for search', '1', '1', '1');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('2', 'Temporary not available', '532', 'Momentan nicht verfügbar', 'Temporary not available', '1', '1', '1');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('3', 'Archived', '496', 'Archiviert', 'Archived', '1', '1', '1');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('4', 'Hidden by approvers to check', '533', 'Von den Approvern entfernt, um geürpft zu werden', 'Hidden by approvers to check', '0', '1', '0');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('5', 'Not yet available', '534', 'Noch nicht veröffentlicht', 'Not yet available', '0', '1', '0');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('6', 'Locked, visible', '821', '', '', '1', '1', '0');
INSERT INTO `cache_status` (`id`, `name`, `trans_id`, `de`, `en`, `allow_user_view`, `allow_owner_edit_status`, `allow_user_log`) VALUES ('7', 'Locked, invisible', '822', '', '', '0', '0', '0');
oliver

[quote="sp2ong"]
Hm, I am not sure that what we want to exchange between OC Nodes use API.[/quote]

I am sure we want to exchange at least:

user accounts basic info like name
user account authentication info, if user previously allowed it
table caches, caches_logs, pictures, cache_desc, coordinates, cache_attrib

We should begin with user, when it works, extend to replicate caches/cache_logs/cache_desc/coordinates/pictures an exchange cache_logs in the last step.

Maybe it is required that small servers only exchange user and basic cache-info for performance reason and database size.

But if we dont get a real replication running, we can never compete with gc.com.
sp2ong

OK I have instaled latest version OKAPI on OC US and we can test on 2 sites this OKAPI

http://opencaching.pl/okapi/introduction.html
http://opencaching.us/okapi/introduction.html
RVRoadTrip

On OCUS,we have cache types that other nodes do not have. Will these be ignored by the API?
wrygiel

There will be only 4 "offical" cache types. All other types will display too, but they won't be documented.

BTW, the installation on opencacing.us is missing some files. It won't work properly.
sp2ong

Now is upload full OKAPI package.

But short lin without www don't working and for test we are must use www.opencaching.us/okapi instead opencaching.use/okapi

I don't know where is problem
Antworten