gs-JS-API

Experimental JavaScript library for the GNU social API.

The interface is a bit weird. It might change significantly in the future.
This is mainly just an excuse for me to play with JavaScript Promises.

Note: In the current version, most methods use the JSON endpoints of the GNU social API. In the future, it is planned to switch to XML by default with the option to switch to JSON for the endpoints that support it.

Example

Most methods function similarly.
Here, we're getting the configuration information, then the version information about the GNU social instance located at http://sn.chromic.org:

// Create the GS Object and pass it to the provided callback
gs('http://sn.chromic.org', function (instance) {
    // Inside the callback, we use .config() to fetch the configuration information.
    instance.config()
        .then(function (json) {
            // The .config() call succeeded, print the data on the console.
            console.log(json);
        }, function (err) {
            // The .config() call failed, print the error message on the console.
            console.log(err);
        });

    // On the same GS Object, we use .version() to fetch the configuration information.
    instance.version()
        .then(function (json) {
            // The .version() call succeeded, print the data on the console.
            console.log(json);
        }, function (err) {
            // The .version() call failed, print the error message on the console.
            console.log(err);
        });
});

Interface

"Constructor"

gs(url, callback[, apiRoot])

Returns: Object
Description: Get an Object representing a GNU social instance.
Arguments:

• url: The URL of a GNU social instance
  Type: String

• callback: Function to be called once the GNU social Object has been setup
  Type: Function

• apiRoot: If you know the URL of the targeted instance's API root, you can provide it here. This saves a few HTTP requests in the Object's initialization stages.
  Type: String

Instance Information

gs.config()

Returns: Promise
Description: Get instance configs.
If the Promise is successful, the resolve argument will be a JSON Object.

gs.groups()

Returns: Promise
Description: Get a list of local groups.
If the Promise is successful, the resolve argument will be a JSON Object.

gs.version()

Returns: Promise
Description: Get instance version.
If the Promise is successful, the resolve argument will be a JSON Object.

Groups

gs.group(id)

Returns: Promise
Description: Get details on a specific group.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted group.
  Type: String

gs.group.members(id)

Returns: Promise
Description: Get the members of a specific group.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted group.
  Type: String

gs.group.timeline(id)

Returns: Promise
Description: Get group timeline.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted group.
  Type: String

Users

gs.user(id)

Returns: Promise
Description: Get details on a specific user.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted user.
  Type: String

gs.user.favorites(id)

Returns: Promise
Description: Get a list a user's favorite notices.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted user.
  Type: String

gs.user.foaf(username)

Returns: Promise
Description: Get a user's FOAF information.
If the Promise is successful, the resolve argument will be an XML Document.
Note: This method requires a server-side proxy.
Arguments:

• username: The username of the targeted user.
  Type: String

gs.user.groups(id)

Returns: Promise
Description: Get a list of groups a specific user is subscribed to.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted user.
  Type: String

gs.user.isMember(username, groupname)

Returns: Promise
Description: Check whether a user is part of a specific group.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• username: The username of the targeted user.
  Type: String

• groupname: The name of the targeted group.
  Type: String

gs.user.subscribed(id)

Returns: Promise
Description: Get the list of people a specific user is subscribed to (i.e.: following).
If the Promise is successful, the resolve argument will be an XML Document.
Arguments:

• id: The ID of the targeted user.
  Type: String

gs.user.subscribers(id)

Returns: Promise
Description: Get list of user's subscribers (i.e.: followers).
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted user.
  Type: String

gs.user.timeline(id)

Returns: Promise
Description: Get a user's home timeline.
If the Promise is successful, the resolve argument will be a JSON Object.
Arguments:

• id: The ID of the targeted user.
  Type: String