Ruby library for UserApp

If you don't have a UserApp account, you need to create one.

• App Id: The App Id identifies your app. After you have logged in, you should see your App Id instantly. If you're having trouble finding it, follow this guide.

• Token: A token authenticates a user on your app. If you want to create a token for your logged in user, follow this guide. If you want to authenticate using a username/password, you can acquire your token by calling api.user.login(...)

Install using gem:

$ gem install userapp

Load the library:

require 'userapp'

api = UserApp::API.new(:app_id => "YOUR APP ID")

If you want to create a client with additional options the easiest way is to pass the options as shown below.

api = UserApp::API.new(:debug => true, :throw_errors => true)

This client has no hard-coded API definitions built into it. It merly acts as a proxy which means that you'll never have to update the client once new API methods are released. If you want to call a service/method all you have to do is look at the API documentation and follow the convention below:

result = api.[service].[method](:[argument] => [value])

Please note that you need to mark the method that you want to call with one or several arguments. I.e. api.user.get() will NOT call the API user.get, instead, it will only instantiate a service called user.get. So to call a method on a service you need to pass arguments. If you don't have any arguments, you can just pass nil. I.e. the correct call would look like api.user.get(nil).

The API user.login and its arguments login and password translates to:

login_result = api.user.login(:login => "test", password => "test")

The API user.invoice.search and its argument user_id translates to:

invoices = api.user.invoice.search(:user_id => "test123")

The API property.save and its arguments name, type and default_value translates to:

property = api.property.save(:name => "my new property", :type => "boolean", :default_value => true)

The API user.logout without any arguments translates to:

api.user.logout(nil)

Options determine the configuration of a client.

• Version (version): Version of the API to call against. Default 1.
• App Id (app_id): App to authenticate against. Default nil.
• Token (token): Token to authenticate with. Default nil.
• Debug mode (debug): Log steps performed when sending/recieving data from UserApp. Default: false.
• Secure mode (secure): Call the API using HTTPS. Default: true.
• Base address (base_address): The address to call against. Default: api.userapp.io.
• Throw errors (throw_errors): Whether or not to throw an exception when response is an error. I.e. result {"error_code":"SOME_ERROR","message":"Some message"} results in an exception of type UserApp::ServiceError.

Options are easiest set in the object constructor. I.e. as shown below:

api = UserApp::API.new(:debug => true)

Options can also be set after object creation using api.get_options().[option name], as shown below:

api.get_options().debug = true

A more detailed set of examples can be found in /examples.

api = UserApp::API.new(:app_id => "YOUR APP-ID")
api.user.save(:login => "johndoe81", :password => "iwasfirst!111")

api = UserApp::API.new(:app_id => "YOUR APP-ID")

api.user.login(:login => "johndoe81", :password => "iwasfirst!111")
api.user.save(:user_id => "self", :first_name => "John", :last_name => "Doe")

api.user.logout(nil)

api = UserApp::API(:app_id => "YOUR APP-ID", :token => "YOUR TOKEN")

search_result = api.user.search(:filters => {:query => '*bob*'}, :sort => {:created_at => 'desc'})

puts search_result.items

If you want to configure the client to call a specific API version you can do it by either setting the version option, or by calling the client using the convention api.v[version number]. If no version is set it will automatically default to 1.

Since no version has been specified, this call will be made against version 1 (default).

api.user.login(:login => "test", :password => "test")

Since the version has been explicitly specified using options, the call will be made against version 2.

api = UserApp::API.new(:version=2)
api.user.login(:login => "test", password => "test")

Since the version has been explicitly specified, the call will be made against version 3.

api.v3.user.login(login => "test", password => "test")

Sometimes to debug an API error it's important to see what is being sent/recieved from the calls that one make to understand the underlying reason. If you're interested in seeing these logs, you can set the client option debug to true.

api = UserApp::API.new(:debug => true)
api.user.login(:login => "test", :password => "test")

When the option throw_errors is set to true (default) the client will automatically throw a UserApp::ServiceError exception when a call results in an error. I.e.

begin
	api.user.save(:user_id => "invalid user id")
rescue UserApp::ServiceError => error
	if error.error_code == "INVALID_ARGUMENT_USER_ID"
		# Handle specific error
		puts "Invalid user!"
	end
end

Setting throw_errors to false is more of a way to tell the client to be silent. This will not throw any service specific exceptions. Though, it might throw a UserApp::Error, UserApp::InvalidServiceError, or UserApp::InvalidMethodError.

result = api.user.save(:user_id => "invalid user id")

if result.respond_to?('error_code') and result.error_code == "INVALID_ARGUMENT_USER_ID"
	# Handle specific error
	puts "Invalid user!"
end

Even though this client works as a proxy and there are no hard-coded API definitions built into it, there are still a few tweaks that are API specific.

In other words:

login_result = api.user.login(:login => "test", :password => "test")

Is exactly the same as:

login_result = api.user.login(:login => "test", :password => "test")
api.get_options().token = login_result.token

In other words:

api.user.logout(nil)

Is exactly the same as:

api.user.logout(nil)
api.get_options().token = nil

MIT - For more details, see LICENSE.