Introducing the Opera Link API

By Esteban Manchado Velázquez

Introduction

Opera Link - our service for synchronising your browser information such as bookmarks and history across different locations - has been around for some years now, but so far it has been available only in Opera products. That has finally changed! With the Opera Link API now available, you can now develop your own applications that can both read and write Opera Link data.

The Opera Link API is accessible through HTTP and is REST-based. It can output either XML or JSON, and you can use whatever server-side language you are comfortable with when writing your application. The authentication uses OAuth, which means each application you write will have its own application key and can be identified uniquely.

Later articles will showcase examples of libraries in different languages, and look at our OAuth implementation in more detail. This article will provide a gentle introduction to using the main features of the Opera Link API.

Note: This article is really intended to familiarise readers with the basic commands available inside the Opera Link API, and how it works. Subsequent articles will cover development of actual applications.

Contents:

The linkapidebugger tool

To follow the examples in this article, we have created a simple Python command line tool that allows you to easily make requests to the API server. To use it, you need to:

  • Download the linkapidebugger tool to your local drive
  • Make sure you have an Opera account (also known as a My Opera, Dev Opera, or Opera Link account). If you don't have one, you can get an Opera account from My Opera
  • Install a working Python installation on your machine. Many platforms come with Python already installed, but you might want to install the latest version from the Python site anyway just in case.
  • Unzip the linkapidebugger into its own directory

Once you have everything in place, you have to execute the tool the first time to connect to your account by opening the command line/terminal, accessing the directory you unpacked the tool into and entering the following command:

python linkapidebugger.py

Now go to the URL it gives, which will look something like this:

https://auth.opera.com/service/oauth/authorize?oauth_token=RTw5HwxMd89yym1U1FUd3wLPPtY06qIQ&oauth_callback=oob

Enter your Opera account details and select Grant access — the page will respond by giving you a verifier code. If you go back to the command line/terminal you'll see that it is asking you to enter the verifier code. Enter the code at the blinking prompt, and press Enter/Return, and the standard prompt will come up.

Now you can use the linkapidebugger to follow the rest of the article.

Simple debugger command examples

The utility has two modes of operation: GET and POST. The GET method simply receives a URL and makes the request. The POST method needs an arbitrary number of named parameters that will be read from the terminal. To make a GET request, simply give the URL as a parameter:

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/children

To make a POST request, on the other hand, you need to give the URL to POST to, and add POST as a second parameter:

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/children POST

linkapidebugger will then ask you for all the parameters to send in with the POST request. It reads extra parameters from the keyboard, one per line, eg api_method=delete. You end your data with an empty line, ie just press Enter/Return twice after your data has finished:

api_method=create
item_type=bookmark
title=Bookmark title
uri=http://example.com
 
[now press enter/return twice to complete the parameters list]

The full terminal input and output will look like this: (command entries in black/strong emphasis, program outputs in gray font with no emphasis):

$> python linkapidebugger.py https://link.api.opera.com/rest/bookmark/children
Response properties
===================
{'status': '200', 'content-location': 'https://link.api.opera.com/rest/bookmark/children?oauth_nonce=34340886&oauth_timestamp=1286984865&oauth_consumer_key=test_desktop_key&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=ATvn1SKopv1i0lA5CaELgWiaqgI5S7w5&oauth_signature=yHW3jrERm2eBGACLxkDu3L1lWnk%3D', 'transfer-encoding': 'chunked', 'vary': 'Authorization', 'server': 'Apache/2.2.9 (Debian) mod_wsgi/2.5 Python/2.5.2', 'date': 'Wed, 13 Oct 2010 15:47:45 GMT', 'content-type': 'application/json; charset=utf-8'}

Response body
=============
[
    {
        "item_type": "bookmark_folder", 
        "id": "4E1601F6F30511DB9CA51FD19A7AAECA", 
        "properties": {
            "show_in_panel": false, 
            "title": "Trash", 
            "show_in_personal_bar": false, 
            "panel_pos": -1, 
            "type": "trash", 
            "personal_bar_pos": -1
        }
    }, 

[...followed by loads more JSON bookmark entries...]

Note: in future examples, we will just show the complete listing like this, so you can easily reference what you need to enter, and what the response should be.

API basics

The Opera Link API allows you to access the data stored in your Opera Link account. You can query specific items like a single bookmark or note, parts of your data like a whole bookmark folder, or your whole data set, and also make changes to the data and add new items. With it you can write your own applications to manage your bookmarks, display or share your SpeedDial on a website, import or export your data in whatever format you need, etc.

The Opera Link API supports different data types. The current list is bookmarks, SpeedDial and notes, but this list will be extended in the future. Some operations are common to all data types, while others behave differently or are only available for certain data types. The complete Link API reference documentation is available on our documentation pages.

Basically, all data is available in URLs under https://link.api.opera.com/rest/<data_type>. Every item has a unique ID that identifies it, and when operating on a specific piece of data, you typically use a URL like https://link.api.opera.com/rest/<data_type>/<unique_id>. You've already seen some basic examples in the Simple debugger command examples section above. Below we will look at some examples specific to all the different API features.

As a general rule, GET requests only query information (ie they never make any changes to your data), while POST requests are used to modify data (ie they create, update or delete items).

If you add ?api_output=xml at the end of the query URL, you will get XML output. If you want the whole contents of your account (not just the root folder contents) you can ask for descendants instead of children.

Creating your first bookmark

The next example will create a new bookmark in your root folder. To do that, you have to fire a POST request to https://link.api.opera.com/rest/bookmark/ containing at the very least the api_method, item_type, title and uri parameters.

The parameter api_method should have the value create. The parameter item_type should have the value bookmark. title and uri can have whatever title and URI you want for your new bookmark. For example:

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/ POST

api_method=create
item_type=bookmark
title=My first API bookmark
uri=http://opera.com

The complete terminal input and output will look something like this:

$> python linkapidebugger.py https://link.api.opera.com/rest/bookmark/ POST
Reading extra parameters from the keyboard, one per line
(e.g. 'api_method=delete')
End with an empty line (ie. just pressing ENTER twice after your data)
api_method=create
item_type=bookmark
title=My first API bookmark
uri=http://opera.com
 
Response properties
===================

{'status': '200', 'content-length': '241', [... more output ...]}
 
Response body
=============

[
  {
    "item_type": "bookmark", 
    "id": "319A38DB4581426DA48CAB58C2528FD4", 
    "properties": {
      "created": "2010-08-18T12:59:13Z", 
      "uri": "http://opera.com", 
      "title": "My first API bookmark"
    }
  }
]

Note that the output will be the newly created bookmark, including a unique ID for it generated by the server. You will need this ID to further manipulate the element later.

Try repeat your first GET request from above now: you should see your new bookmark popping up in the results.

Moving around

Now let's look at something slightly different - say that you want to move some bookmarks to a different folder, or simply change their order. To do this, you can use the API method move. This method moves a given item to a position relative to another item. For example, it allows us to move item A before, after, or inside, item B (the latter works only if item B is a folder). So, say that the bookmark you just created got the id 319A38DB4581426DA48CAB58C2528FD4 and you wanted to move it before the Trash folder (you need to substitute your own ID in the request and parameter below). To do this you can issue a POST request something like so:

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/319A38DB4581426DA48CAB58C2528FD4/ POST

And try parameters like this:

api_method=move
reference_item=4E1601F6F30511DB9CA51FD19A7AAECA
relative_position=before

The complete input and output looks like this:

$> python linkapidebugger.py https://link.api.opera.com/rest/bookmark/319A38DB4581426DA48CAB58C2528FD4/ POST
Reading extra parameters from the keyboard, one per line
(e.g. 'api_method=delete')
End with an empty line (ie. just pressing ENTER twice after your data)
api_method=move
reference_item=4E1601F6F30511DB9CA51FD19A7AAECA
relative_position=before
 
  [... same output as above ...]

Again, try issuing the first GET request again to check your updated bookmarks.

Trashing bookmarks

Another common operation will be moving bookmarks to the Trash folder. You can just move them yourself with the move command, but as it's a relatively common operation, there is a handy shortcut available to do it: the trash command. To move a bookmark to the Trash, simply issue a POST request to the appropriate element with the api_method set to trash, like so (again, substitute your own ID):

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/319A38DB4581426DA48CAB58C2528FD4/ POST

And enter the following parameters:

api_method=trash

The complete input and output is as follows:

$> python linkapidebugger.py https://link.api.opera.com/rest/bookmark/319A38DB4581426DA48CAB58C2528FD4/ POST
Reading extra parameters from the keyboard, one per line
(e.g. 'api_method=delete')
End with an empty line (ie. just pressing ENTER twice after your data)
api_method=trash
 
  [... same output as above ...]

If you now issue a GET children request, you won't see the element — you'll only see the trash folder. You will have to use the descendants request to get the contents of Trash, or use the children request giving the ID of the Trash folder like so:

python linkapidebugger.py https://link.api.opera.com/rest/bookmark/4E1601F6F30511DB9CA51FD19A7AAECA/children/

the complete input and output looks like so:

$> python linkapidebugger.py https://link.api.opera.com/rest/bookmark/4E1601F6F30511DB9CA51FD19A7AAECA/children/
[
  {
    "item_type": "bookmark", 
    "id": "319A38DB4581426DA48CAB58C2528FD4", 
    "properties": {
      "created": "2010-08-18T12:59:13Z", 
      "uri": "http://opera.com", 
      "title": "My first API bookmark"
    }
  }
]

Checking your SpeedDial

But enough about bookmarks. After all, there are more data types covered by the API! We'll now move on to SpeedDial, which works a bit differently from bookmarks. Here, items don't get a unique id generated by the server. Instead, the unique id for the item is simply its position in the SpeedDial. If you want to check the contents of your SpeedDial, you can simply issue a children request like this:

python linkapidebugger.py https://link.api.opera.com/rest/speeddial/children/

The input and output looks like so:

$> python linkapidebugger.py https://link.api.opera.com/rest/speeddial/children/


Response properties
===================

{'status': '200', [... more output ...]}
 
Response body
=============

[
  {
    "item_type": "speeddial", 
    "id": "1", 
    "properties": {
      "reload_interval": "2147483646", 
      "title": "Opera Portal beta", 
      "uri": "http://redir.opera.com/speeddials/portal/", 
      "reload_only_if_expired": "0", 
      "reload_enabled": "0"
    }
  },
   
    [... more SpeedDial entries ...]
]

Creating entries in your SpeedDial is very easy, although you need to make sure you use empty speed dial positions, otherwise, you'll get an error! For example, to create a new speed dial entry in position 6, you'd use this request:

python linkapidebugger.py https://link.api.opera.com/rest/speeddial/6/ POST

And parameters like this:

api_method=create
title=My first SpeedDial entry
uri=http://my.opera.com

the full input and output will look something like this:

$> python linkapidebugger.py https://link.api.opera.com/rest/speeddial/6/ POST
Reading extra parameters from the keyboard, one per line
(e.g. 'api_method=delete')
End with an empty line (ie. just pressing ENTER twice after your data)
api_method=create
title=My first SpeedDial entry
uri=http://my.opera.com
 
[
  {
    "item_type": "speeddial", 
    "id": "6", 
    "properties": {
      "position": "6", 
      "uri": "http://my.opera.com", 
      "title": "My first SpeedDial entry"
    }
  }
]

Notes

Notes work almost exactly like bookmarks, but instead of the title parameter, they have content. Notes also have an optional uri field, in this case it represents the URI the content has been taken from. Nevertheless notes should be trivial to use if you have already mastered bookmarks. For example, checking the notes in the root folder is done like so:

$> python linkapidebugger.py https://link.api.opera.com/rest/note/children/
 
Response properties
===================

{'status': '200', 'content-length': '191', [... more output ...]}
 
Response body
=============
 
[
  {
    "item_type": "note_folder", 
    "id": "A9AAFED0976111DC85AC8946BEF8D2DC", 
    "properties": {
      "item_type": "trash", 
      "title": "Trash"
    }
  }
]

Summary

This has been just a quick introduction to the Opera Link API to get you started. Be sure to check the reference documentation for the full details and possibilities, and watch this space for further articles covering the API and OAuth.

Esteban is a quality assurance engineer, project manager, developer, and other things at Opera. He has worked on projects like Opera Link, Opera Unite, My Opera, Dev Opera and others. Outside work, he likes music, playing drums, reading... and hacking, of course.


This article is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported license.

Comments

The forum archive of this article is still available on My Opera.

No new comments accepted.