OKAPI Project - API for OpenCaching sites

[wrygiel]

Hey!

I am a developer from Poland. I would like you to comment on a project
we've just started. Would you be willing to join it?

http://code.google.com/p/opencaching-api/

It's a pre-release BETA version. We have it already installed on our
production site ( http://opencaching.pl/okapi/ ), but there are a
couple of unresolved issues which should be fixed prior the release.

In next couple of days I will be adding some working examples on how
to use the API.

[solar22]

Hello,

I'm solar22 - opencaching.de developer.
Currently i'm working on a REST api.
I see your api is actualy more finished as our.
Maybe i can use your construct for oc.de

You can see the status of my work here: http://gruessung-online.de/oc/doc.html

Greetings

solar22

[wrygiel]

I'm glad we paired up then!

I would be REALLY very very happy if OKAPI would be included in opencaching.de. I will gladly help you with the integration.

[wrygiel]

Can I access your source code somewhere?

[solar22]

Currently i develop on my local machine.
I have problems with the upload to github.com repo. (Access denied.)
I think, during the next week, i'm able to upload the first code.
Then i can post the link here.

Greetings.

[sp2ong]

Wojtek add support for GPX and other GPS-compatible output formats.
http://code.google.com/p/opencaching-api/issues/detail?id=33

[wrygiel]

I did, just yesterday.
http://www.opencaching.pl/okapi/services/caches/formatters/gpx.html

[mic@]

Is this project (OKAPI) open for the public?
http://www.opencaching.pl/okapi/introduction.html

Should we advertize it a little bit?
Or do You want to keep it secret until it works?

[wrygiel]

Sure, you may advertize it.

(But method signatures are not yet fixated. I plan on doing this in a couple of days.)

[wrygiel]

(This is in response to a private message by oliver.)

> Hi wrygiel,

> i am Oliver, developer at oc.de. I am very happy to read your
> posting. The first impression is "wow".

Thanks very much

I'm glad to hear you liked it because one of my goals is to have OKAPI
working on both our sites (and later - possibly on every other
opencaching site).

> New oc.de code is based on smarty and has several incompatible
> changes and many improvements. However, some old beginner-stuff from
> my php-beginning time in 2003 is still present.

Currently, OKAPI does not use much of the "legacy code". In fact, the
only things I use are "sql" and "sqlValue" functions + some global
variables. So, the only important thing is the database structure.

I believe it is possible that the current version of OKAPI would work
with opencaching.de "as is", without any need for modifications, but I
would have to see your database to be sure. However, you may just try
it, installation is simple - just 5 minutes of work (see project main
page). It requires PHP 5.3.

In case of incompatibilities, this could be helped with some crude
conditions like "if ($GLOBALS['absolute_site_URI'] ==
'http://opencaching.de/') { sql1 } else { sql2 }".

If you choose to use OKAPI, I would expect for all code changes to be
commited into the main OKAPI repository. I DON'T want you to develop
your own OKAPI branch, I hope you understand why - the project is all
about compatibility!

In other words - I will be happy to accept all your changes to OKAPI,
*IF* exactly the same changes will go to opencaching.pl. And I really
hope you will agree on this - it would be the best option for both of
our sites.

> I have to view it in detail, but as i remember, the most important
> change for the API is the table "cache_status". Maybe oc.pl does not
> contain boolean columns allow_user_view allow_owner_edit_status
> allow_user_log . It is absolutly required to follow these settings -
> maybe waldek can add that columns to oc.pl code, too (if required).

I think I don't understand what you're saying. Why would API need a
change in table "cache_status"? Also, I don't know about these allow_*
columns. (I am new to OpenCaching project, I've first seen this
database only two months ago. I do not know much...)

> We at oc.de need to decide first what license to apply to the cache
> data. As i remember, oc.pl does CC licensing for cache data?

Our "Terms of Use" page is in BETA, as the rest of OKAPI. In fact,
I just copied parts of the "opencaching.com API" licence, which I
found apropriate.

Do you think it is possible for us to agree on a common licence, for
both of our sites?

> Let me know if you need write permission to git repository
> (repository is public read). Or if you prefer to keep it in you own
> repository.

I want to keep OKAPI code separate. I think this will simplify
development and deployment process. The idea is to FIRST have things
changed in OKAPI repo, THEN merge them into all production sites.

[oliver]

Moved the topic to the private subforum.

[sp2ong]

Maybe it will be interested for test Oliver to installl OKAPI on OC DE and we can look how to optimize and tune or change to use this API to OC Nodes ?

[oliver]

Hi wrygiel,

private messages are private. Else, i would create a topic in the public forum. So, for the future, it would be nice not to see my private messages in the forum or ask me before you publish it. No problem in this case and it will be no problem for most of my private messages at all.

However, you may just try
it, installation is simple - just 5 minutes of work (see project main
page). It requires PHP 5.3.

Okay, thats the first problem. Our linux distribution does not support PHP 5.3. Moving to newer distribution is still on Todo. If you cannot remove the PHP 5.3 depency, i will try to do the migration soon, but it will take some time to prepare everything.

If you choose to use OKAPI, I would expect for all code changes to be commited into the main OKAPI repository
(...)
In other words - I will be happy to accept all your changes to OKAPI,
*IF* exactly the same changes will go to opencaching.pl. And I really
hope you will agree on this - it would be the best option for both of
our sites.

I absolutly agree that there should be only one version and that this version should run on both sites without modification and customisation. 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. If the API does not follow that rules, we could get legal implications, because most times we set that status, there are problems with the copyright and we already had contact with a lawer who wants to see money from us, if we still publish the listing.

I think I don't understand what you're saying. Why would API need a change in table "cache_status"? Also, I don't know about these allow_* columns.

It is realy simple:

Each cache has a status-id (1, 2, 3, ...). When you want to know if a all users are allowed to view that cache listing, you only need to get the cache-status-id from table caches and read allow_user_view from table cache_status for that id. If it is 1, all users are allowed to view that cache. If it is 0, the user needs special permission - this may be because he is the owner of the listing or the user is admin.

It will be no problem to add these new database columns to the oc.pl databse. Then your API works again with both sites without modifications.

Our "Terms of Use" page is in BETA, as the rest of OKAPI. In fact,
I just copied parts of the "opencaching.com API" licence, which I
found apropriate.

Okay, then i have to check if the terms of use are affected by copyright laws. In germany, you cannot simply copy anything from anywhere. Especially terms of use are copyright protected, because the company has paid much money to get the terms of use from a lawer. It depends on the specific content ...

Do you think it is possible for us to agree on a common licence, for
both of our sites?

I hope thats possible! We should commit at least for some sort of "opencaching network terms of use". Each node should support that terms of use. If a node wants to allow more than that, its okay. But a node should not restrict their thers of use more than the common OC network terms of use.

"OCN-TOU" = Opencaching Network - Terms Of Use

E.g. 1) If we decide not to allow commercial use in the "OCN-TOU", oc.pl may allow it for listings originating from oc.pl (but not for those from oc.de).

E.g. 2) If we decide to allow commercial use in the "OCN-TOU", oc.de may not forbid it.

It will be realy hard work to find "OCN-TOU" where all nodes aggree on. The more simply and clear they are, the better it is.


With kind regards,

Oliver

[oliver]

Maybe it will be interested for test Oliver to installl OKAPI on OC DE and we can look how to optimize and tune or change to use this API to OC Nodes ?

At the moment i am working on the migration of some oc.se-code (which has been migrated from oc.pl) to oc.de. There is a bunch of other work todo.

But solar22 could install the API on his local development machine and start with testing. He already did some coding on a oc.de-API ... with the OKAPI-project we can stop to work on our own API.

[wrygiel]

> private messages are private. Else, i would create a topic in the
> public forum.

Okay, sorry about that. It seemed to me that our discussion would be
interesting for all other OC site-admins.

> Our linux distribution does not support PHP 5.3. Moving to newer
> distribution is still on Todo. If you cannot remove the PHP 5.3
> depency, i will try to do the migration soon, but it will take some
> time to prepare everything.

It would be hard. OKAPI is deeply dependant on namespaces - one of the
new features in PHP 5.3.

> I absolutly agree that there should be only one version and that
> this version should run on both sites without modification and
> customisation.

Great!

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

Okay. There are two ways of dealing with that:

1. Oc.pl can incorporate that changes that you've made in oc.de. We
need Waldek's opinion on this - probably he is the one who would be
doing this. (I am responsible for OKAPI code only.)

2. We can make OKAPI work with both database structures with *the same
interface*. I am not 100% sure if this can be done, but it seems
possible.

To solar22: If I am not mistaken, in both cases, you'd be the one to
modify parts of the OKAPI code. I can give you commit rights, but
you'd have to have an account at Google.

Ad1. In this case you will modify OKAPI to work with oc.de, and then
we (you, Waldek an me) have to update oc.pl code with proper changes.

Ad2. In this case you will modify OKAPI to work both with oc.de and
oc.pl - you will be adding stuff like "if (I'm running on oc.pl) { do
womething } else { do something else }". (I'll call them "multisite
conditions" from now on.)

I think, the second approach would be easier for starters. Later, we
can get rid of these "mutli-site conditions", one by one.

What do you think? (Waldek? Oliver?)

> It will be no problem to add these new database columns to the oc.pl
> databse. Then your API works again with both sites without
> modifications.

If Waldek agrees to do this, then its fine with me! (In this case, I
will add support for this to OKAPI.) If not, then solar22 and I would
have to do more of "multi-site conditions".

> "OCN-TOU" = Opencaching Network - Terms Of Use

> E.g. 1) If we decide not to allow commercial use in the "OCN-TOU",
> oc.pl may allow it for listings originating from oc.pl (but not for
> those from oc.de).

> E.g. 2) If we decide to allow commercial use in the "OCN-TOU", oc.de
> may not forbid it.

> It will be realy hard work to find "OCN-TOU" where all nodes aggree
> on. The more simply and clear they are, the better it is.

Seems reasonable, but I'm really not good at legal stuff.

I tend to think that commercial is good, it powers the progress. Well,
I'm not 100% sure about that, but I think that, for example,
developers might be more keen to invest their time in an Android app,
if they had an option to "switch commercial" one day.