NoseRub

This will be the table of contents for the documentation.

The Protocol

The API

NoseRub 0.5.4 comes with the first small portion of an API for NoseRub.

General and Authentification

Right now, the API only returns JSON. Authentification takes place through an API key that is passed along with the username in the URL to make an API call. If the authentication did not work out (or you did not activate the API key), you will get a 404 error as result. Every API call starts like this:

http://identoo.com/api/USERNAME/API_HASH/json/

So, when in the following sections, you see a command, you just have to append it to the URL schema above. Example:

http://identoo.com/api/USERNAME/API_HASH/json/locations/

Return values

Everytime you call the API, you will get a return code, a return message and, in some cases, a dataset. The structure is always the same:

{
    "data" : [],
    "code" : 0,
    "msg" : "ok"
}

In this case here, no dataset was returned. When the code is 0, the API call was successfull. When an error occured, the code will always be nagative, Right now, there is only one error message:

-1 : dataset not found

This is returned, when you try to access a dataset, which could not be found, or to which you have no access to.

Location

This methods can be used to set your current location and get the locations you previously added. Right now, there is no method here, to add, edit or delete locations through the API.

locations

Returns an array with id and name of the locations you previously added through the webinterface. Example:

{
    "data" : [
        {
            "Location" : {
                "id" : "1",
                "name" : "Home"
            }
        }
    ],
    "code" : 0,
    "msg" : "ok"
}

locations/set/LOCATION_ID

By specifying the LOCATION_ID, your social stream at your NoseRub profile will show, that you currently are at this location. The result will look like this:

{
    "data" : [],
    "code" : 0,
    "msg": " ok"
}

If you specified a non-existing location id, or one that does not belong to you, you will get this error message:

{
    "data" : [],
    "code" : -1,
    "msg" : "dataset not found"
}

Preface

We understand NoseRub not only as an application, like what is running on Identoo.com and which everyone can download and install on their own servers. We want even more freedom for the people who want to use NoseRub.

That means, that we want to give a user the possibility to choose their NoseRub application. Right now, only one version is available, which was implemented in PHP. Others might prefer other languages or might want to have a different approach to how the application should work. We encourage that and therefore want others to implement their very own version of NoseRub.

After a long week in Berlin, a lot of new input needed to be processed and the new idea of the NoseRub protocol is no longer what currently is used in the version presented on Identoo.com.

Right now, only NoseRub-IDs can be used as an endpoint for a contact, even when someone has a blog where he/she lists all his/her other web accounts in XFN or FOAF. I want to make use of that and allow people to connect through this, too.

What still is true about the Noserub protocol, regards the three main parts of NoseRub: Identity-URL + Profile + Contacts = NoseRub

What will be described here, is not the current implementation, but the implementation of how it should be and how it will be in NoseRub 1.0, although there is no release date set for that.

Identity-URL

The Identity part for NoseRub is a single URL, under which the all information about the user can be accessed. It should be an OpenID, but that also can mean, that OpenID login can be delegated to an already existing OpenID. An example for such a URL could be http://identoo.com/dirk.olbertz/. SSL support for the Identity-URL should be available.

Each Identity-URL can be endpoint of a contact relation.

There must be some kind of metadata on that page, that identifies itself as a NoseRub-Identity-URL. That should be similar to how OpenID works.

Profile

In the metdata or content area of the page that can be accessed through the Identity-URL, profile information as XFN/Microformat and/or FOAF should be accessible - either embedded or referred through further URLs.

For XFN, all links where the rel-Attribute contains "me" are regarded as web-accounts for that Identity. In FOAF, the tag foaf:OnlineAccount will be used for that kind of information. All other FOAF- and microformat-data should be used as proposed by the appropriate standard. (List of full usage for the fields to follow!)

All web accounts hold a specific type to be able to filter and categorize them. Currently, there are nine account types:

• Photo
• Video
• Audio
• Link
• Text
• Micropublish
• Events
• Documents
• Locations

(Full list of web accounts like flickr, del.icio.us and twitter, along wth their type to follow.)

Open questions

1. How should things like the "About" text be stored in FOAF/microformats?


2. How should RSS-Feeds be specified with the account types above? (In FOAF and XFN)

Contacts

In the metdata or content area of the page that can be accessed through the Identity-URL, profile information as XFN and/or FOAF should be accessible - either embedded or referred through further URLs.

All links with the rel-attribute, that do not have "me" as part of the rel-attribute, will be considered as contacts.