The OKAPI Project
:: OpenCaching API Reference
OKAPI is a public API project for National OpenCaching sites (also known as
OpenCaching Nodes).
- It provides your site with a set of useful well-documented API methods,
- Allows external developers to easily read public OpenCaching data,
- Allows read and write private (user-related) data with OAuth 3-legged authentication.
The project is aiming to become a standard API for all National OpenCaching.xx sites.
This OKAPI installation provides API for the
http://www.opencaching.us/ site.
Check out other OKAPI installations:
How can I use OKAPI?
We assume that you're a software developer and you know the basics.
OKAPI is a set of simple (REST) web services. Basicly, you make a proper HTTP request,
and you receive a JSON-formatted data, that you may parse and use within your own application.
Example. Click the following link to run a method that prints out the list of
all available methods:
You've made your first OKAPI request! This method was a simple one.
It didn't require any arguments and it didn't require you to use a Consumer Key.
Other methods are more complex and require you to use
your own API key.
Authentication Levels
Each OKAPI method has a minimum authentication level.
This means, that if you want to call a method which requires "Level 1"
authentication, you have to use "Level 1" authentication or higher
("Level 2" or "Level 3" will also work).
Important: Most developers will only need to use "Level 1" authentication
and don't have to care about OAuth.
-
Level 0. Anonymous. You may call this method with no extra
arguments.
some_method?arg=44
-
Level 1. Simple Consumer Authentication. You must call this
method with consumer_key argument and provide the key which has
been generated for your application on the Sign up page.
some_method?arg=44&consumer_key=a7Lkeqf8CjNQTL522dH8
-
Level 2. OAuth Consumer Signature. You must call this method
with proper OAuth Consumer signature (based on your Consumer Secret).
some_method
?arg=44
&oauth_consumer_key=a7Lkeqf8CjNQTL522dH8
&oauth_nonce=1987981
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1313882320
&oauth_version=1.0
&oauth_signature=mWEpK2e%2fm8QYZk1BMm%2fRR74B3Co%3d
-
Level 3. OAuth Consumer+Token Signature. You must call this method
with proper OAuth Consumer+Token signature (based on both Consumer Secret and
Token Secret).
some_method
?arg=44
&oauth_consumer_key=a7Lkeqf8CjNQTL522dH8
&oauth_nonce=2993717
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1313882596
&oauth_token=AKQbwa28Afp1YvQAqSyK
&oauth_version=1.0
&oauth_signature=qbNiWkUS93fz6ADoNcjuJ7psB%2bQ%3d
GET or POST?
Whichever you want. OKAPI will treat GET and POST requests as equal.
You may also use the HTTP Authorization header for passing OAuth arguments.
OKAPI does not allow usage of PUT and DELETE requests.
Most of the methods return simple objects, such as list and dictionaries
of strings and integers. Such objects can be formatted in several ways using
common formatting parameters:
Important: Almost all of the returned datatypes are extendible. This means,
that (in future) they may contain data that you do not expect to be there.
Such data will be included in backward-compatible manner, but still you should remember about
it in some cases (i.e. when iterating over attributes of an object). The additional data might
include special elements in GPX files or special keys in JSON responses.
Your software must ignore such occurances if it doesn't understand them!
Some methods expose some special formatting of their own, for example, they may return
a JPEG or a GPX file. Such methods do not accept common formatting parameters.
OAuth Dance URLs
If you want to use Level 3 methods, you will have to make "the OAuth dance" (series of
method calls and redirects which provide you with an Access Token).
The three OAuth request URLs defined in the OAuth specification are:
Things you should pay attantion to:
-
The oauth_callback argument of the request_token method is required.
As the OAuth 1.0a specification states, it should be set to "oob" or a callback
URL in case you have a web front-end for your application.
For most OAuth client libraries, you just should provide
"http://www.opencaching.us/okapi/services/oauth/request_token?oauth_callback=oob"
as the request_token URL, to get it started. Later, probably you'd want to switch "oob"
to something else.
-
The oauth_verifier argument of the access_token method is also required.
When user authorizes your application, he will receive a PIN code (OAuth verifier). You
have to use this code to receive your Access Token.
-
Access Tokens do not expire (but can be revoked). This means, that once the user
authorizes your application, you receive a "lifetime access" to his/her account (it does
not expire after several hours). User may still revoke access to his account from your
application - when this happens, you will have to redo the autorization dance.
How can I participate in OKAPI development?
OKAPI is Open Source and everyone is welcome to participate in the development.
In fact, if you'd like a particular method to exist, we encourage you to
submit your patches.
We have our Issue tracker.
You can use it to contact us!
You may also contact some of
the developers directly,
if you want.
Visit project homepage for details:
http://code.google.com/p/opencaching-api/
List of available methods
Currently available OKAPI web services (methods):
|