Client Libraries

Podio Ruby client

This is the official Ruby client for accessing the Podio API. Besides handling setup and authentication it also provides idiomatic Ruby methods for accessing most of the APIs operations. This client library is designed to be minimal and easily integrable into your projects.

Install

Podio is packaged as a gem:

shell


gem install podio

Or you can use Bundler:

ruby


gem 'podio'

Configuration

The main way of using the Podio library is via a singleton client, which you set up like this:

ruby


Podio.setup(:api_key => 'YOUR_API_KEY', :api_secret => 'YOUR_API_SECRET')

This initializes a Podio::Client object and assigns it to a thread-local, which is used by all methods in this library.

Authentication

After the configuration you need to authenticate against the API. The client supports two ways of authentication:

Web Server Flow

The default OAuth flow to be used when you authenticate Podio users from your web application.

ruby


    Podio.client.authenticate_with_auth_code('AUTHORIZATION_CODE', redirect_uri)

We recommend using Omniauth for authenticating from a rack-based Ruby app. The Rails sample application on Github demonstrates how to implement the OAuth flow in Ruby on Rails using Omniauth.

App authentication

If you need only to interact with a single Podio app from your code and you don't want to bother with a full login flow, we recommend using this approach.

ruby


    Podio.client.authenticate_with_app('APP_ID', 'APP_TOKEN')

Username and Password Flow

If you're writing a batch job or are just playing around with the API, this is the easiest to get started. Do not use this for authenticating users other than yourself, the web server flow is meant for that.

ruby


    Podio.client.authenticate_with_credentials('USERNAME', 'PASSWORD')

Basic Usage

After you configured the Podio.client singleton you can use all of the wrapper functions to do API requests. The functions are organized into modules corresponding to the official API documentation. The functions follow a common naming pattern that should be familiar to ActiveRecord users. For example:

ruby


# Getting an item
Podio::Item.find(42)

# Posting a status message on space with id 23
Podio::Status.create(23, {:value => 'This is the text of the status message'})

If there is a method missing or you want to do something special, you can use the Faraday connection directly. This allows you to do arbitrary HTTP requests to the Podio API with authentication, JSON parsing and error handling already taken care of. The same examples would look like this:

ruby


# Getting an item
response = Podio.connection.get('/item/42')
response.body

# Posting a status message on space with id 23
response = Podio.connection.post do |req|
  req.url '/status/space/23/'
  req.body = {:value => 'This is the text of the status message'}
end
response.body

All the wrapped methods either return a single model instance, an array of instances, or a simple Struct in case of pagination:

ruby


# Find all items in an app (paginated)
items = Podio::Item.find_all(app_id, :limit => 20)

# get count of returned items in this call
items.count

# get the returned items in an array
items.all

# get count of all items in this app
items.total_count

Active Podio

The Podio API is based on REST requests passing JSON back and forth, but we have tried to make the use of this client an experience more similar to using ActiveRecord from Ruby on Rails. That means that all find methods returns model instances with attributes cast to the expected type (string, integer, boolean, datetime, etc.). Also, models can be instantiated using an object array from params in Rails, just like with ActiveRecord Models.

While the models can be used directly from this gem, we encourage everyone using Podio in a Rails project to add models that extends the standard models:

ruby


class Item < Podio::Item # Inherits from the base model in the Podio gem

  # Your custom methods, e.g.:
  def application
    @app_instance ||= Application.find(self.app_id)
  end
end

Error Handling

All unsuccessful responses returned by the API (everything that has a 4xx or 5xx HTTP status code) will throw an exception. All exceptions inherit from Podio::PodioError and have three additional properties which give you more information about the error:

ruby


begin
  Podio::Space.create({:name => 'New Space', :org_id => 42})
rescue Podio::BadRequestError => exc
  puts exc.response_body      # parsed JSON response from the API
  puts exc.response_status    # status code of the response
  puts exc.url                # uri of the API request

  # you normally want this one, a human readable error description
  puts exc.response_body['error_description']
end

On instance methods, however, exceptions are handled in a way more similar to ActiveRecord. These methods returns a boolean indicating if the API request succeeded or not, and makes the code, description and parameters available when the request fails:

ruby


@space_contact = SpaceContact.new({:name => 'Fritz Smith', :birthdate => 70.years.ago})
if @space_contact.create
  # Success
else
  # Error, check:
  # @space_contact.error_code
  # @space_contact.error_message
  # @space_contact.error_parameters
end

Full Example

ruby


require 'rubygems'
require 'podio'

Podio.setup(:api_key => 'YOUR_API_KEY', :api_secret => 'YOUR_API_SECRET')
Podio.client.authenticate_with_credentials('YOUR_PODIO_ACCOUNT', 'YOUR_PODIO_PASSWORD')

# Print a list of organizations I'm a member of
my_orgs = Podio::Organization.find_all

my_orgs.each do |org|
  puts org.name
  puts org.url
end

Example app on Github

The Rails sample application on Github demonstrates how to authenticate and read/write items to Podio.

Client Libraries

Podio Ruby client

Install

Configuration

Authentication

Web Server Flow

App authentication

Username and Password Flow

Basic Usage

Active Podio

Error Handling

Full Example

Example app on Github

Meta