This document is also available in French.

Blogmarks Atom API Specification

Introduction

This API is based upon the Atom API Specification 09. 

The AtomAPI is an application level protocol for publishing and editing web resources. 
The protocol at its core is the HTTP transport of Atom formatted representations.

Atom Terminology

  • Atom Feed

An Atom Feed is composed of logically organized Atom Entries.

  • Atom Entry

An Atom Entry is a part of an Atom Feed and represents a ressource.

  • PostURI

This URI is dedicated to ressource creation. Atom formated ressources are POSTed to this URI in order to be recorded on the server.

  • EditURI

This URI is dedicated to ressource, retrieval, modification and suppression. Each ressource has its own EditURI.

  • FeedURI

This is were you can obtain Atom Feeds.

Blogmarks.net introduces two types of ressources : blogmarks and tags. A detailed description of these ressources' format can be found in the AtomXmlFormatSpec?.

REST Architecture

The Atom API was created with REST architecture conformity in mind. This architecture introduces simple rules aimed at making the developer's life easier. The main idea was to correctly use the HTTP protocol verbs : GET, PUT, POST, DELETE.

Many articles and tutorials about REST can be found easily.

Authentication

Any user has to be authenticated in order to create, modify or delete a ressource. The Blogmarks.net authentication system implements Atom Authentication as described by Mark Pilgrim.

Authenticated requests require two dedicated HTTP headers : 

Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="bob", PasswordDigest="quR/EWLAV4xLf9Zqyw4pDmfV9OY=", 
        Nonce="d36e316282959a9ed4c89851497a717f", Created="2003-12-15T14:43:07Z"
  • Username : blogmarks.net user login
  • PasswordDigest? : clientside-generated digest
  • Nonce : Random string used to generate digest
  • Created : Timestamp used to generate digest

Implementation examples can be found in the AtomApiExamples?.

URIs

Blogmarks.net main ressources is the blogmark. Any registered and authenticated user can create blogmarks. He also can fetch public tags Atom descriptions and manipulate his private tags.

blogmarks.net ressource URIs :

Type de la ressource PostURI EditURI FeedURI
blogmark http://api.blogmarks.net/marks (POST) http://api.blogmarks.net/marks/123 (GET, PUT, DELETE) http://api.blogmarks.net/marks (GET)
public tag N/A http://api.blogmarks.net/tags/<tag_name> (GET) http://api.blogmarks.net/tags (GET)
private tag http://api.blogmarks.net/user/<login>/tags (POST) http://api.blogmarks.net/user/<login>/tags/<tag_name> (GET, PUT, DELETE) http://api.blogmarks.net/tags (GET)

NB : public and private tags' FeedURI is the same. Parameters used to search for one type or the other are described later on.

Searches are performed by sending GET requests to a FeedURI. Marks FeedURI returns 30 most recent marks by default. Tags FeedURI returns 30 most popular tags.

Parameters available when searching for marks :

Name Possible values Description Default value
last integer from -1 to ... Limit number of results 30
offset positive integer First result offset, for paging... 0
search string Searches for string in blogmarks (title, desc) + tags
tags string (*) Searches for requested public tags
private_tags string (*) Recherche les blogmarks contenant les tags privés indiqués (*).
related regexp ???
author string <user> Searches only in <user>'s marks
private true | false If true, also search in private marks false
month integer 01 to 12 if used with year, search only in marks posted durint that month
year integer YYYY Restrict search to marks posted during that year
out rss Return RSS 1.0 feed (instead of Atom)
level positive integer <level> Restrict search to marks posted by at least <level> users
order_by issued|modified|created|popularity Results sorting mode issued
order_type asc|desc Results dorting direction desc

(*) A list of tags can be specified, using the space char as separator. Tags using more than one word should be surrounded with double quotes (eg. "open source software").

Parameters available when searching for tags :

Name Possible values Description Default value
last integer from -1 to ... Limit number of results 30
offset positive integer First result offset, for paging... 0
title string Searches for string in tags' titles
summary string Searches for string in tags summaries
author string Restrict search to author's private tags
private true | false If true, also search for private tags false
user string Restrict search to user's tags
minPopularity positive integer Search for tags used by more integer times by users

Cool URIs

In order to give developers more ease, we set up simple URIs that are aliases to full URIs with parameters. Here they are :

Ressource Creation

In order to create a ressource (blogmark or tag), the client must POST that ressource's description to the corresponding PostURI. This action requires client authentication.

Server's response (if operation was successful) :

  • Response code : HTTP 201 Created
  • Response body : Created ressource Atom description

Ressource Modification

In order to update a ressource (blogmark or provate tag), the client must PUT ressource's new description to its EditURI. This action requires the client to be authenticated and to own the ressource.

Server's response (if operation was successful) :

  • Response code : HTTP 205 Reset Content

Ressource Suppression

In order to suppress a ressource, the client must send a DELETE HTTP request to ressource's EditURI. This action requires the client to be authenticated and to own the ressource.

Server's response (if operation was successful) :

  • Response code : HTTP 200 Ok

Ressource Retrieval

In order to retrieve a ressource, the client must send GET HTTP request to ressource's EditURI. This operation requires client to be authentified if the ressource is private.

Server's response (if operation was successful) :

  • Response code : HTTP 200 Ok
  • Response body : Requested ressource Atom description

Error Handling

Server returning a 4xx or 5xx HTTP code means that an error occured while processing the request. If so, response body describes the error as XML.

  • 401 Authorization Required HTTP authentication header is missing or provides invalid informations.formations erronées.
  • 404 Not Found Requested URI does not reference a ressource or search returned no results.
  • 500 Internal Server Error Server-side error occured. It is described in response body.

See also : DeveloperDocs, AtomApiXmlSpec