A Ruby wrapper for the Partigi API, adapted from Grackle by Hayes Davis.
Partigi is a service that helps you choose your next cultural items, share short reviews and keep track of what you have consumed and own.
The Partigi API is an almost-REST based Atom API where we offer you almost all data and functionality that you have in the website.
There is also a complete documentation of the API.
gem install oauth
gem install partigirb -s http://gemcutter.org
Since Partigi started to require OAuth in all its API requests they support two authorization modes: the common OAuth specification (http://oauth.net/core/1.0a/) for read-write access and OAuth with a slightly modification for read-only access, which just consists of skiping the oauth_token when signing the requests.
Regardless of the access method used you will need to register your application and get a consumer_key
and a consumer_secret
, used in both access methods. (http://www.partigi.com/applications)
client = Partigirb::Client.new('consumer_key', 'consumer_secret')
client = Partigirb::Client.new('consumer_key', 'consumer_secret')
client.set_callback_url('http://myapplication.test/partigi')
request_token = client.request_token
# At this point we must redirect the user to Partigi so he can authorize our application to access
# his profile, we can get the authorization url with request_token.authorize_url
# Once we are back Partigi will give us the parameter oauth_verifier, which we will use
# to get the access token
client.authorize_from_request(request_token.token, request_token.secret, oauth_verifier)
# Now our client is fully authorized to call write methods for the user
A request to Partigi servers is done by translating Partigi URL paths into a set of chained method calls, just changing slashes by dots. Each call is used to build the request URL until a format call is found which causes the request to be sent. In order to specify the HTTP method use:
?
for HTTP GET!
for HTTP POST (in this case you will need to use a client with authentication)
A request is not performed until either you add the above signs to your last method call or you use a format method call.
Note: Any method call that is not part of a valid API request path will be chained to the request that Partigirb sends to the server, so that when the client finds a format call (method call ending with ? or !) a wrong request will be sent and a PartigiError will be raised. For example:
client.wrong.items.index?
or
client.wrong
client.items.index?
In the second case we do the wrong call and the right one in separated sentences, however the wrong call is chained anyway (in that case the client method clear
may be used to flush the chain).
The response format is specified by a method call with the format name (atom, json or xml). Notice that the only format fully implemented on Partigi API at the moment is atom, which is the default used by the wrapper.
The simplest way of executing a GET request is to use the ?
notation, using the default format.
client.users.show? :id => 'johnwayne' # http://www.partigi.com/api/v1/users/show.atom?id=johnwayne
Also you can force the format:
client.users.show.json? :id => 'johnwayne' # http://www.partigi.com/api/v1/users/show.json?id=johnwayne
For POST requests just change ?
by !
:
client.reviews.update! :id => 123, :status => 1 # POST to http://www.partigi.com/api/v1/reviews/update.atom
- All parameters are URL encoded as necessary.
- If you use a File object as a parameter it will be POSTed to Partigi in a multipart request.
- If you use a Time object as a parameter, .httpdate will be called on it and that value will be used
The returned values are always OpenStruct objects (wrapped in Partigirb::PartigiStruct) containing the response values as attributes.
If the response contains several entries the client returns an Array of OpenStruct objects.
When using Atom format Partigi returns some XML elements using namespaces. In those cases the elements are mapped to attributes by convention, for example: namespaceName:attribute
becomes namespaceName_attribute
There are two special cases to be aware of in regard to PartigiStruct:
-
Every attribute which name is equal to any of the Ruby Object methods (e.g
type
) will be mapped to a method on the struct starting with an underscore (e.g_type
). -
XML elements that appear repeated with different type values will turn into a unique struct with one method per type. For instance:
<content type="text">Some text</content> <content type="html"><p>Some html</p></content>
Will be accessed by
result.content.text
andresult.content.html
, both returning a ruby string.
In case Partigi returns an error response, this is turned into a PartigiError object which message attribute is set to the error string returned in the XML response.
A way to check if our client is correctly authorized for write access or to just get the current user's information is by using the verify_credentials method, which will return either the PartigiStruct object with user's information or a PartigiError object in case of authorization failure.
client.verify_credentials
- json
- mime-types
Copyright (c) 2009 Alvaro Bautista & Fernando Blat, released under MIT license