linkaGoGo REST API (Beta)

Table of contents

  1. Introduction
  2. API
  3. Examples
  4. Planned future features
  5. Usage
  6. Showcases
  7. Third-Party showcases

Introduction

This document describes the REST API for linkaGoGo. With this API, third-party applications can query and modify linkaGoGo bookmarks and folders.

The API is based on the principles of REST.

The API uses a small set of HTTP operations for its functionality. The operations are GET (retrieve), POST(create), PUT(update) and DELETE(delete). These operations can be applied on Folders and Bookmarks.

API

In the linkaGoGO REST API every folder and bookmark has its own URL(URI=Unique Resource Indicator). A folder is identified by a URI ending with '/folder/{folder_id}', bookmarks are identified by a URI ending with '/bookmark/{bookmark_id}' URIs ending with folderitems/{folder_id} list the contents (bookmarks and subfolders) of a folder. As you may have noticed each folder has two URIs, one URI to address the folder itself and one URI to address the contents of the folder.

URIs

The fully qualified URIs are: Every URI points to a XML document that represents the folder, folder contents or bookmark. Note instead of private you can also use {username} with the linkagogo name of the user. Replace the id with the ids for the folder or bookmark. The URI for Home(root) folder looks like this:

  • http://www.linkagogo.com/api/rest/private/folder
  • http://www.linkagogo.com/api/rest/private/folderitems
  • Note the absence of the {folder_id} argument. The Home folderitems URI is typically the URI an application starts with.

  • http://www.linkagogo.com/api/rest/private/favorites
  • This link returns your bookmarks that are marked as your favorites

  • http://www.linkagogo.com/api/rest/private/added
  • This link returns your 20 latest added bookmarks.

  • http://www.linkagogo.com/api/rest/private/popular
  • This link returns your 20 most used bookmarks.

  • http://www.linkagogo.com/api/rest/private/recent
  • This link returns your 20 most recently visited bookmarks.

  • http://www.linkagogo.com/api/rest/private/reminders
  • This link returns your active reminders.

  • http://www.linkagogo.com/api/rest/private/search?search={search string}
  • Search folders and bookmarks for the specified search string. The search string can be specified through a url parameter named search. The search value can use the following grammar:
  • and; all verbs need to be found. this is the default when no and/or is specified. For example: weather and boston
  • or; either one of the verbs need to be found. For example: redsox or yankees
  • '-'; with a hyphen you can indicate that the search should exclude results with the verb. For example: -yankees
  • ""; verbs enclosed by the double qoutes are taken literraly; For example: "red sox"

    Methods

    The HTTP methods GET, POST, PUT and DELETE can be applied to these URIs. Here a table that describes what each of the methods do when applied to a URI.

    MethodDescription
    .../folder/{folder_id}
    GETReturns the XML that represent the folder
    POSTCreates a bookmark or folder in the folder based on the XML that is in the request
    PUTUpdates the folder based on the XML that is in the request
    DELETEDelete the folder
    .../folderitems/{folder_id}
    GETReturns the XML that represent list of subfolder and bookmarks in the folder
    .../bookmark/{bookmark_id}
    GETReturns the XML that represent the bookmark
    PUTUpdates the bookmark based on the XML that is in the request
    DELETEDeletes the bookmark
    .../favorites
    GETReturns the XML that represent list the favorite bookmarks of the user
    .../added
    GETReturns the XML that represent the last 20 bookmarks that have been added.
    .../popular
    GETReturns the XML that represent the 20 most visited bookmarks.
    .../recent
    GETReturns the XML that represent the 20 most recent visited bookmarks.
    .../reminders
    GETReturns the XML that represent the active reminder bookmarks.
    .../search?search={search string}
    GETReturns the XML with folders and bookmarks that are found.

    XML

    Each of the three URIs have their own flavor of XML. A sample folder XML looks like this:
    <xbel>
      <folder public="yes">
        <title>My Business folder</title>
      </folder>
    </xbel>
    

    All the XML fragments have the outer <xbel> tag. public is an attribute. folder and title are tags.

    NameDescription
    .../folder/{folder_id}
    Returns one <folder> tag containing:
    titletag containing the name of the folder
    desctag containing the description of the folder
    uriattribute with the uri for the folder
    contentsattribute with the folderitems uri for the folder
    parentattribute with the parentfolder uri for the folder
    publicattribute indicating whether a folder is public(yes/no)
    recursiveattribute indicating that subfolder should be set to the public value (yes/no). (Only valid with a PUT request containing the public attribute)
    addedattribute with the creation date of the folder
    .../folderitems/{folder_id}
    Returns one or more <folder> and <bookmark> tags containing:
    titletag containing the name of the folder/bookmark
    uriattribute with the uri for the folder/bookmark
    contentsattribute with the folderitems uri for the folder (folder only)
    parentattribute with the parentfolder uri for the folder/bookmark
    redirectattribute indicating the redirect url for the website. Use this url to update linkaGoGo visit statistics for a website (See also href). Preferred for visiting a website (bookmark only)
    hrefattribute indicating the url for the website. Use this url to directly go to the website. (See also redirect). Use redirect url to visit the site (bookmark only)
    .../bookmark/{bookmark_id}
    Returns one <bookmark> tag containing:
    titletag containing the name of the bookmark
    desctag containing the description of the bookmark
    keywordstag containing the keywords of the bookmark
    uriattribute with the uri for the bookmark
    parentattribute with the parentfolder uri for the bookmark
    redirectattribute indicating the redirect url for the website. Use this url to update linkaGoGo visit statistics for a website (See also href). Preferred for visiting a website
    hrefattribute indicating the url for the website. Use this url to directly go to the website. (See also redirect). Use redirect url to visit the site
    favoriteattribute indicating whether a bookmark is a favorite (yes/no)
    addedattribute with the creation date of the bookmark
    changedattribute with the date the bookmark was last changed
    visitedattribute with the date the bookmark was last visited
    visitsattribute with the number of visits for this bookmark
    reminderattribute indicating the reminder type
    rssattribute indicating the rss url for the bookmark
    imageattribute indicating the image url for the bookmark
    smarturlattribute indicating the smart url for the bookmark
    aliasattribute indicating the alias for the bookmark
    ratingattribute indicating the rating for the bookmark (1-5)

    Encoding

    All the XML documents use the UTF-8 encoding.

    Security

    To access the API you need to authenticate with your linkaGoGo account-name and password. When you access the API through your browser you will automatically get a login dialog. The API supports the HTTP Basic and Digest authentication methods. Digest is much safer then Basic, as it doesn't send your password over the Internet. See the HTTP Authentication specification RFC 2617 for more details.

    You can also use SSL to access the API. Just use the https// prefix. Note all returning uri will have https:// protocol prefixes.

    Compression

    In order to improve throughput (and therefor is faster) and preserve bandwidth you can indicate that you want compressed response by setting the Accept-Encoding header. Compressions we support are gzip, compress, x-compress and x-gzip.

    Examples

    For now we have a sample on how to use the API using the browser. The samples show how to query folders and bookmarks.

    More useful applications are written with languages such as Java, C, C++, PHP, Javascript, Ajax etc.
    If you are a plugin developer for the Firefox, Internet Explorer or Google SidePanels you can use the API to build / replace a linkaGoGo powered bookmark manager. Other ideas could be a Windows Explorer like application for browsing your bookmarks. Or you can integrate linkaGoGo bookmarking in your Custom solution. Note we provide lucrative discounts for subscription resellers. Contact us at
    associates@linkagogo.com

    Browser session example

    You can use the browser to communicate with the API (get only). Just copy and paste the uri's in your browser's address bar.

    First get the contents of the root folder:
    http://www.linkagogo.com/api/rest/private/folderitems
    Note the browser will prompt for the linkagogo username and password.

    Get the contents of a subfolder. Copy the content attribute of one of the folders in your clipboard, then paste it in the browser address bar:
    http://www.linkagogo.com/api/rest/private/folderitems/{folder_id}

    Get the properties of the subfolder. Copy the uri value of one of the folders in your clipboard, then paste it in the browser address bar:
    http://www.linkagogo.com/api/rest/private/folder/{folder_id}

    Get the properties of a bookmark. Copy the uri value of one of the bookmarks in your clipboard, then paste it in the browser address bar:
    http://www.linkagogo.com/api/rest/private/bookmark/{bookmark_id}

    Visit the bookmark's website. Copy the redirect attribute of one of the bookmarks in your clipboard, then paste it in the browser address bar:
    http://www.linkagogo.com/go/To?url={bookmark_id}
    Note the website should appear.

    Now get the properties of the bookmark again. Copy the uri value of the bookmarks in your clipboard, then paste it in the browser address bar:
    http://www.linkagogo.com/api/rest/private/bookmark/{bookmark_id}
    Note the visits and last_visited attributes are now updated.

    Planned future features

    Usage

    Here some rules to regulate the usage of this API.

    Fair use

    Subscriptions

    The API is available to Plus and Premium members. SSL support will require the HTTPS premium option. Future additional APIs may require other premium options. The look is based on the ITunes look.

    Showcases

    linkaGoGo Browser

    LinkaGoGo Browser, an example of using the linkaGoGo Web API and stylesheets. See here the xslt source.

    linkaGoGo Organizer

    LinkaGoGo Organizer. A small application to quickly organize your folders and bookmarks. Drag or bookmark the link LinkaGoGo Organizer into your Links / Bookmarks toolbar for easy and quick access.

    Third-Party showcases

    lggrem2rss - linkaGoGo Reminders RSS

    lggrem2rss, is a python script for converting linkaGoGo reminders into an RSS feed. The script retrieves your reminders through the linkaGoGo Web API and then converts them into an RSS file, which can then be hosted on your webserver. It also describes how you can run the script on a regular basis using a cron job. A nice example on how to access the linkaGoGo WEB API from Python. Provided by Broobles

    Your Application/Plugin here

    If you developed your own application / plugin, you can have it featured on this page. Send an email with a description, small screenshot and a link to support@linkagogo.com