Stable Version of the PHP REST Client and a Developer Tutorial have been released

As announced a few month ago, there is a new REST client for PHP developers (restclient-php). Now we can proclaim the first stable release of version 1.0.0. This PHP library is really easy to use and supports all functions of the BibSonomy REST API. It also provides an integrated CSL-processor (citeproc-php) that helps you to render bibliographies.

In addition, there is a tutorial for the use of restclient-php which contains some useful examples scripts.

We hope that helps you to develop your own App for BibSonomy.

Happy tagging,
Sebastian

Feature of the Week: New REST Client for PHP

We spent some time developing a new full-featured REST Client in PHP in order to make it much easier for you to develop new Apps for the BibSonomy universe.

The new REST client library comes with a lot of new features:

• It's full-featured that means the client supports the whole functionality of the API.
• It contains a model such that it is convenient for you to work with the data.
• It supports Basic Auth as well as OAuth authentication methods.
• It's easy to integrate in your PHP App, since we have used composer, a powerful tool in order to integrate and autoload requirements of 3rd party software.
• You can output a fetched set of publications as a CSL-rendered publication list in your favorite citation style.

In order to use the restclient-php library you need to do three steps:

1. Install the library via composer and include the autoloader file.
   
   Installing Composer locally is a matter of just running the installer in your project directory:
   
   curl -sS https://getcomposer.org/installer | php
   
   Then, add the restclient to the requirements of your project. Run the following command on a terminal within your project folder:
   
   php composer.phar require academicpuma/restclient-php:1.0.0-alpha
    
2. Create an Accessor. This object is required to authenticate your App on the REST API of BibSonomy. You can choose between two authentication methods, Basic Auth or OAuth. For Basic Auth this would be:
   
   <?php

require 'path/to/vendor/autoload.php';
use AcademicPuma\RestClient\Accessor\BasicAuthAccessor;

$accessor = new BasicAuthAccessor('http://www.bibsonomy.org', [your-username], '[your-apikey]');
?>
 
3. Create a RESTClient object and perform a request. This object is your interface to BibSonomy. This class provides all supported functions to get, create, update, and delete posts, tags, documents, user and groups. For example:
   
   <?php

use AcademicPuma\RestClient\RESTClient;
use AcademicPuma\RestClient\Config;

$restClient = new RESTClient($accessor);
//choose Resource type and tags
$restClient->getPosts(Config\Resourcetype::BIBTEX, Config\Grouping::USER, [username], ['tag1', 'tag2']);
?>
   
   Now, you can choose the format. There are four options: XML, CSL (JSON), Model (PHP Objects), Bibliography (CSL-rendered publication list):
   
   

   <?php
   
   
   //output xml
   echo $restClient->xml();
   
   //output CSL
   echo json_encode($restClient->csl());
   
   //use the model
   $posts = $restClient->model();
   foreach($posts as $post) {
       echo $post->getResource()->getTitle()."<br />\n";
   }
   
   //print a bibliography in your preferred style and language
   echo $restClient->bibliography('apa', 'en-US');
   
   ?>
   

Currently restclient-php is considered as unstable alpha version. If you encounter  any errors or problems, feel free to report an issue on our code repository.

Happy tagging,
Sebastian.

Feature of the week: creating concepts via the REST API

As a careful reader of our blog, you will have notived that tag relations, or concepts are a feature of BibSonomy which is important to us but probably not often used. Some previous blog posts where we promoted concepts are

• http://blog.bibsonomy.org/2007/04/feature-of-week-relations.html
• http://blog.bibsonomy.org/2007/11/feature-of-week-retrieve-resources-by.html
• http://blog.bibsonomy.org/2010/04/feature-of-week-relations-last-major.html

We recently started to better support concepts with BibSonomy's REST API by implementing the creation of new concepts in the Java REST client. In this post I give you an example how you can access this functionality. Since we start from scratch, this post is also a good introduction on how to use the Java REST client in general.

Setting up Maven

Using Maven for build management really simplifies many things, so let's use it. First, create a directory for the project and change to that directory. Everything you do, will now happen there. Then inside that directory, create a directory for the source code:

mkdir -p src/main/java

and then create a file called pom.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"                                                                                                        
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                                                                                               
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <name>Test</name>
  <groupId>com.example</groupId>
  <artifactId>test</artifactId>
  <version>0.0.1</version>
  <repositories>
    <repository>
      <id>dev.bibsonomy.org</id>
      <url>http://dev.bibsonomy.org/maven2/</url>
    </repository>
  </repositories>
  <dependencies>
    <dependency>
      <groupId>org.bibsonomy</groupId>
      <artifactId>bibsonomy-rest-client</artifactId>
      <version>2.0.43</version>
    </dependency>
    <dependency>
      <groupId>org.bibsonomy</groupId>
      <artifactId>bibsonomy-model</artifactId>
        <version>2.0.43</version>
    </dependency>
  </dependencies>
</project>

You can now already test, if everything is OK by calling mvn install which should print you some lines with one of the last being

[INFO] BUILD SUCCESS

Writing and calling Java code

Now you can start to write the first Java code. Create the file src/main/java/Test.java with the following content:

class Test {

    public static void main(String args[]) {
       System.out.println("Hello World!");
    }
}

You can compile this file into a JAR by calling mvn install again. The resulting JAR file test-0.0.1.jar will be in the target folder. You can run this class with the command

java -cp target/test-0.0.1.jar Test

or alternatively with

mvn exec:java -Dexec.mainClass="Test"

The latter is the preferred choice for the next steps, since you will include some libraries whose dependencies Maven automatically resolves.

Calling the REST API

Change the file Test.java to the following code:

import java.util.*;                                                                                                                                          
import org.bibsonomy.common.enums.*;
import org.bibsonomy.model.*;                                                                                                                                
import org.bibsonomy.model.logic.*;
import org.bibsonomy.model.enums.*;                                                                                                                          
import org.bibsonomy.rest.client.*;

class Test {

    public static void main(String args[]) {
        RestLogicFactory rlf = new RestLogicFactory("http://www.bibsonomy.org/api");

        LogicInterface logic = rlf.getLogicAccess("jaeschke", "YOUR-API-KEY-HERE");

        List<Post<BibTex>> posts = logic.getPosts(BibTex.class, GroupingEntity.USER, "jaeschke", null, null, null, null, Order.ADDED, null, null, 0, 1);

        for (Post<BibTex> post: posts) {
        BibTex publication = post.getResource();
            System.out.println(publication.getTitle());
        }
    }
}

Note that you have to change the line

LogicInterface logic = rlf.getLogicAccess("jaeschke", "YOUR-API-KEY-HERE");

to use your BibSonomy user name instead of "jaeschke". You also must insert your API key which you can get from BibSonomy's settings page. When you compile (mvn install) and then run (mvn exec:java -Dexec.mainClass="Test") this class, it should print the title of my last publication post. You now change that code again, to finally create a concept.

Creating a concept with the REST API

import java.util.*;
import org.bibsonomy.common.enums.*;
import org.bibsonomy.model.*;
import org.bibsonomy.model.logic.*;
import org.bibsonomy.model.enums.*;
import org.bibsonomy.model.util.*;
import org.bibsonomy.rest.client.*;

class Test {

    public static void main(String args[]) {
        LogicInterface logic = new RestLogicFactory().getLogicAccess("jaeschke", "YOUR-API-KEY-HERE");

        Tag concept = new Tag("science");
        concept.addSubTag(new Tag("physics"));
        concept.addSubTag(new Tag("chemistry"));
        concept.addSubTag(new Tag("biology"));

        logic.createConcept(concept, GroupingEntity.USER, "jaeschke");
    }
}

Again, you have to change your credentials in the call to getLogicAccess().

What does the code do? First, it creates an object for the concept "science"

Tag concept = new Tag("science");

and then adds the subconcepts "physics", "chemistry", and "biology":

concept.addSubTag(new Tag("physics"));
concept.addSubTag(new Tag("chemistry"));
concept.addSubTag(new Tag("biology"));

Finally, the concept is stored on the server:

logic.createConcept(concept, GroupingEntity.USER, "jaeschke");

Note that you have to exchange "jaeschke" here by your user name, since one can only create concepts for one's own account. You can then find the concept in your sidebar:

That's it! :-)


Happy programming & tagging!

Feature of the Week: Python Client for the BibSonomy REST-API

This week's feature touches several activities that are currently happening:

1. We are moving our development infrastructure to Bitbucket.
2. We are reanimating the Python client for the REST API.
3. We are developing a CKAN extension.

These activities are somehow related, at least I am bound to mention them all three in this post.

Moving to Bitbucket

As an important step to further open BibSonomy for other developers and ease the development of applications that use the BibSonomy infrastructure, we are migrating to Bitbucket until the next release (which is planned for end of January). At the moment, several extensions and plugins for PHP, Typo3, Android, etc. are moved to the new Bitbucket BibSonomy account.  Other code will follow during the next weeks, in particular the releases currently available at dev.bibsonomy.org.

Python Client

The old Python client for the BibSonomy REST API was no longer maintained and was not really used (and thus not tested) by a real use-case. Since we now have the need for a Python client (see next section), we started the development of a new client.

As a first use-case to test the code and implement some nice functionality, we wrote the small script onefile.py which allows you to download all your posts from BibSonomy into one HTML file which you can use in offline-mode. This is handy for situations where you don't have an internet connection, in particular, since the script allows you to also download all your documents! The documentation which you can access with --help shows you what is possible:

usage: onefile.py [-h] [-u USER] [-t TAG [TAG ...]] [-d]

                  [--bookmark-file BFILE] [--publication-file BFILE]

                  [--css-file CSSFILE] [--no-bookmarks] [--no-publications]

                  [--test]

                  user apikey

Download posts from BibSonomy and store them in a file.

positional arguments:

  user                  BibSonomy user name

  apikey                corresponding API key (get it from

                        http://www.bibsonomy.org/settings?selTab=1)

optional arguments:

  -h, --help            show this help message and exit

  -u USER, --user USER  return posts for USER instead of user

  -t TAG [TAG ...], --tags TAG [TAG ...]

                        return posts that contain the given tags

  -d, --documents       download documents for publications

  --bookmark-file BFILE

                        file name for bookmarks

  --publication-file BFILE

                        file name for publications

  --css-file CSSFILE    write CSS to file

  --no-bookmarks        do not write bookmarks

  --no-publications     do not write publications

  --test                use test data

We are currently very active in improving the script, therefore feedback and suggestions are highly welcome.

CKAN Extension

CKAN is a web-based platform for scientists to manage and publish dataset metadata as Linked Open Data. To better connect datasets with the publications that describe and use them, we are currently implementing a CKAN extension that allows users to connect their datasets with the corresponding publications from BibSonomy. A mockup screenshot shows how we intend to integrate publications into CKAN:

We think that these are good news for all developers, since rapid development of BibSonomy-based applications with Python is now becoming much easier. Feedback and contributions are welcome - the source code is open and free for everybody.

Happy developing!