Ruby PlayNice.ly API Client

This is the official PlayNice.ly API Ruby client library.

For full details of the API see the documentation.

Installation

Details of how to install the client

sudo gem install playnicely

Getting started

Here is a short example script to walk you through the basics of using the client library:

require 'playnicely'

client = PlayNicely::Client.new('username', 'password')

# Get some information about the current user
me = client.current_user
my_projects = client.user_projects(me.user_id)

puts "Logged in as #{me.username}"
puts "Your projects are:"
my_projects.each do |project|
    puts "#{project.name} (ID: #{project.project_id})"
end

# Get the first of your projects so that we can show some items for it
project = my_projects[0]

puts "Items in project #{project.name}"

# list all items
client.project_items(project.project_id).each do |item|
    puts item.subject
end

puts "\nAll done! Now you try"

Reference

You can instantiate the client as follows:

client = PlayNicely::Client.new('username', 'password')

Further authentication information can be found in the main API Documentation.

A quick overview of the available commands:

Projects

To retrieve a single project (API Reference):

client.project(project_id)

This will return the compact version of a project.

client.project(project_id, "full")

Will return the full version of a project.

Milestones

To retrieve a single milestone (API Reference):

client.milestone(project_id, milestone_id)

Items

To retrieve a single item (API Reference):

client.item(project_id,item_id)

Users

To retrieve a single user (API Reference):

client.user(user_id)

Examples:

user_compact = client.user(999) # the detail parameter defaults to '"compact"'
user_full = client.user(999, detail="full")
user_id = client.user(999, detail="id") # returns an integer

To retrieve a list of a user’s projects (API Reference):

client.user_projects(user_id)

Examples:

# How to retrieve a list of projects in each of the available detail levels
projects_compact = client.user_projects(999) # the detail parameter defaults to '"compact"'
projects_full = client.user_projects(999, "full")
projects_id = client.user_projects(999, "id") # returns an integer

Important note: Only projects to which the authenticated user is also a member will be returned. If you require a complete list of all projects for a user, then you must authenticate as that user.

Errors

See the error reference page for more information

# now try again but wrap call and check exception content -- stupid shoulda!
begin
  PlayNicely::Client.new('robbiehudson', 'password').project(1)
rescue PlayNicely::Error => e
  puts "Error type: #{e.error_type}"
  puts "Error message: #{e.error_message}"
end

Will print the following:

Error type: ApiPermissionError
Error message: User ID '2' does not have access to project ID '9999'

Testing

To run the tests just type rake test

Contributing

Please feel free to fork this repository and make any changes you feel are necessary. We will be happy to accept pull requests that we feel will benefit other users of the client.

Help

If you run into problems then you can get in touch with the author (Rob) at support@playnice.ly.