Kentaa API

This gem provides a Ruby library for communicating with the Kentaa API.

Table of Contents

• Installation
• Usage
  • Actions
  • Activities
  • Companies
  • Donation forms
  • Donations
  • Manual donations
  • Newsletter subscriptions
  • Orders
  • Payments
  • Performances
  • Photos
  • Projects
  • Recurring donors
  • Segments
  • Sites
  • Teams
  • Users
  • Avatar
  • Pagination
• Error handling
• Development
• Contributing
• License

Installation

Add this line to your application's Gemfile:

gem 'kentaa-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install kentaa-api

Usage

Create a Kentaa API client using your API key:

require 'kentaa/api'

client = Kentaa::Api::Client.new(api_key: 'your_api_key')

The client is created for the production environment by default. If you want to use the testing environment, then add test: true:

client = Kentaa::Api::Client.new(api_key: 'your_api_key', test: true)

Actions

# List Actions
actions = client.actions       # paginated
actions = client.actions.all   # non-paginated

actions.each do |action|
  action.title  # => "Lorem ipsum"
  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
end

# Get Action by ID or slug
action = client.actions.get(1)
action = client.actions.get("john-doe")

action.title  # => "Lorem ipsum"
action.url  # => "https://demo1.kentaa.nl/actie/john-doe"

# Create a new Action
action = client.actions.create(
  title: "Lorem ipsum",
  description: "Dolorum animi qui nihil iure dolore velit.",
  owner_id: 1
)

action.id  # => 1
action.title  # => "Lorem ipsum"
action.description  # => "Dolorum animi qui nihil iure dolore velit."
action.owner  # => Kentaa::Api::Resources::User

# Update an Action
action = client.actions.update(1, title: "Foobar")

action.title  # => "Foobar"

See also the Kentaa API docs and Kentaa::Api::Resources::Action for all available properties.

Activities

# List Activities
activities = client.activities

activities.each do |activity|
  activity.name  # => "Walking"
end

# Get Activity by ID
activity = client.activities.get(1)

activity.name  # => "Walking"

See also the Kentaa API docs and Kentaa::Api::Resources::Activity for all available properties.

Companies

# List Companies
companies = client.companies       # paginated
companies = client.companies.all   # non-paginated

companies.each do |company|
  company.title  # => "Lorem ipsum"
  company.url  # => "https://demo1.kentaa.nl/bedrijven/kentaa-bv"
end

# Get Company by ID or slug
company = client.companies.get(1)
company = client.companies.get("kentaa-bv")

company.title  # => "Lorem ipsum"
company.url  # => "https://demo1.kentaa.nl/bedrijven/kentaa-bv"

See also the Kentaa API docs and Kentaa::Api::Resources::Company for all available properties.

Donation forms

# List Donation forms
donation_forms = client.donation_forms       # paginated
donation_forms = client.donation_forms.all   # non-paginated

donation_forms.each do |form|
  form.title  # => "Lorem ipsum dolor sit amet"
  form.url  # => "https://demo1.kentaa.nl/form"
end

# Get Donation form
form = client.donation_forms.get(1)

form.title  # => "Lorem ipsum dolor sit amet"
form.owner  # => Kentaa::Api::Resources::User
form.url  # => "https://demo1.kentaa.nl/form"
form.total_amount  # => BigDecimal("95.0")

See also the Kentaa API docs and Kentaa::Api::Resources::DonationForm for all available properties.

Donations

# List Donations
donations = client.donations       # paginated
donations = client.donations.all   # non-paginated

donations.each do |donation|
  donation.first_name  # => "John"
  donation.last_name  # => "Doe"
end

# Get Donation
donation = client.donations.get(1)

donation.first_name  # => "John"
donation.last_name  # => "Doe"
donation.amount  # => BigDecimal("15.0")
donation.entity  # => Kentaa::Api::Resources::Site

See also the Kentaa API docs and Kentaa::Api::Resources::Donation for all available properties.

Manual donations

# List Manual donations
donations = client.manual_donations       # paginated
donations = client.manual_donations.all   # non-paginated

donations.each do |donation|
  donation.first_name  # => "John"
  donation.last_name  # => "Doe"
end

# Get Manual donation
donation = client.manual_donations.get(1)

donation.first_name  # => "John"
donation.last_name  # => "Doe"
donation.amount  # => BigDecimal("15.0")
donation.entity  # => Kentaa::Api::Resources::Site

# Create a Manual donation
donation = client.manual_donations.create(
  first_name: "John",
  last_name: "Doe",
  amount: "15.0"
)

donation.id  # => 1
donation.first_name  # => "John"
donation.last_name  # => "Doe"
donation.amount  # => BigDecimal("15.0")
donation.entity  # => Kentaa::Api::Resources::Site

# Update a Manual donation
donation = client.manual_donations.update(1, first_name: "Jane")

donation.first_name  # => "Jane"

# Delete a Manual donation
client.manual_donations.delete(1)

See also the Kentaa API docs and Kentaa::Api::Resources::ManualDonation for all available properties.

Newsletter subscriptions

# List Newsletter subscriptions
newsletter_subscriptions = client.newsletter_subscriptions       # paginated
newsletter_subscriptions = client.newsletter_subscriptions.all   # non-paginated

newsletter_subscriptions.each do |subscription|
  subscription.email  # => "john.doe@kentaa.nl"
  subscription.subscription_url  # => "https://demo1.kentaa.nl"
end

# Get Newsletter subscription
subscription = client.newsletter_subscriptions.get(1)

subscription.email  # => "john.doe@kentaa.nl"
subscription.subscription_url  # => "https://demo1.kentaa.nl"

See also the Kentaa API docs and Kentaa::Api::Resources::NewsletterSubscription for all available properties.

Orders

# List Orders
orders = client.orders       # paginated
orders = client.orders.all   # non-paginated

orders.each do |order|
  order.first_name  # => "John"
  order.last_name  # => "Doe"
end

# Get Order
order = client.orders.get(1)

order.name  # => "John Doe"
order.total_amount # => BigDecimal("15.0")
order.site  # => Kentaa::Api::Resources::Site

See also the Kentaa API docs and Kentaa::Api::Resources::Order for all available properties.

Payments

# Get Payment
payment = client.payments.get(1)

payment.total_amount  # => BigDecimal("95.0")
payment.donations  # => Array[Kentaa::Api::Resources::Donation]
payment.orders  # => Array[Kentaa::Api::Resources::Order]

See also the Kentaa API docs and Kentaa::Api::Resources::Payment for all available properties.

Performances

Performances are available on an Kentaa::Api::Resources::Action, so you first need to retrieve an Action.

action = client.actions.get(1)

# List Performances
performances = action.performances       # paginated
performances = action.performances.all   # non-paginated

performances.each do |performance|
  performance.title  # => "First tour"
  performance.distance  # => BigDecimal("65.25")
end

# Get Performance
donation = action.performances.get(1)

performance.title  # => "First tour"
performance.distance  # => BigDecimal("65.25")

# Create a Performance
performance = action.performances.create(
  title: "First tour",
  performance_type: "biking",
  performance_at: Time.now,
  distance: "65.25"
)

performance.title  # => "First tour"
performance.distance  # => BigDecimal("65.25")

# Update a Performance
performance = action.performances.update(1, title: "Big tour")

performance.title  # => "Big tour"

# Delete a Performance
action.performances.delete(1)

See also the Kentaa API docs and Kentaa::Api::Resources::Performance for all available properties.

Performance photos

# List Performance photos
photos = performance.photos       # paginated
photos = performance.photos.all   # non-paginated

photos.each do |photo|
  photos.image_url  # => "https://cdn.kentaa.nl/action_performance_photos/file/1/normal_8ce42aeb3bbb1b4964e621b42691f13d4dfa3f21.jpg"
end

# Get Performance photo
photo = performance.photos.get(1)

photo.image_url  # => "https://cdn.kentaa.nl/action_performance_photos/file/1/normal_8ce42aeb3bbb1b4964e621b42691f13d4dfa3f21.jpg"

# Create a Performance photo
photo = performance.photos.create(
  io: File.open("photo.jpeg"),
  content_type: "image/jpeg"
)

photo.image_url  # => "https://cdn.kentaa.nl/action_performance_photos/file/1/normal_8ce42aeb3bbb1b4964e621b42691f13d4dfa3f21.jpg"

See also the Kentaa API docs and Kentaa::Api::Resources::PerformancePhoto for all available properties.

Projects

# List Projects
projects = client.projects       # paginated
projects = client.projects.all   # non-paginated

projects.each do |project|
  project.title  # => "Dignissimos provident rerum enim alias magni asperna..."
  project.target_amount  # => 250000
end

# Get Project by ID or slug
project = client.projects.get(1)
project = client.projects.get("project")

project.title  # => "Dignissimos provident rerum enim alias magni asperna..."
project.target_amount  # => 250000
project.url  # => "https://demo1.kentaa.nl/project/dignissimos-provident"

See also the Kentaa API docs and Kentaa::Api::Resources::Project for all available properties.

Recurring donors

# List Recurring donors
recurring_donors = client.recurring_donors       # paginated
recurring_donors = client.recurring_donors.all   # non-paginated

recurring_donors.each do |recurring_donor|
  recurring_donor.first_name  # => "John"
  recurring_donor.last_name  # => "Doe"
end

# Get Recurring donor
recurring_donor = client.recurring_donors.get(1)

recurring_donor.first_name  # => "John"
recurring_donor.last_name  # => "Doe"
recurring_donor.amount  # => BigDecimal("15.0")
recurring_donor.entity  # => Kentaa::Api::Resources::DonationForm

See also the Kentaa API docs and Kentaa::Api::Resources::RecurringDonor for all available properties.

Segments

# List Segments
segments = client.segments       # paginated
segments = client.segments.all   # non-paginated

segments.each do |segment|
  segment.name  # => "Segment 2"
  segment.url  # => "https://segment-2.demo1.kentaa.nl/"
end

# Get Segment
segment = client.segments.get(1)

segment.name  # => "Segment 2"
segment.title  # => "Aut est maxime nostrum."
segment.url  # => "https://segment-2.demo1.kentaa.nl/"
segment.target_amount  # => 2685

See also the Kentaa API docs and Kentaa::Api::Resources::Segment for all available properties.

Sites

The only method here is current, since there is only one site per API key.

# Get current Site
site = client.sites.current

site.title  # => "Aut est maxime nostrum."
site.description  # => "Maiores ut velit fugiat eos. Quae est nostrum rerum aut et nihil. Sequi eveniet occaecati et est corporis et enim."
site.url  # => "https://demo1.kentaa.nl/"

See also the Kentaa API docs and Kentaa::Api::Resources::Site for all available properties.

Teams

# List Teams
teams = client.teams       # paginated
teams = client.teams.all   # non-paginated

teams.each do |team|
  team.name  # => "Asperiores beatae voluptate qui."
  team.url  # => "https://demo1.kentaa.nl/team/asperiores-beatae-voluptate-qui"
end

# Get Team by ID or slug
team = client.teams.get(1)
team = client.teams.get("team")

team.name  # => "Asperiores beatae voluptate qui."
team.url  # => "https://demo1.kentaa.nl/team/asperiores-beatae-voluptate-qui"
team.total_amount  # => BigDecimal("225.0")

See also the Kentaa API docs and Kentaa::Api::Resources::Team for all available properties.

Users

# List Users
users = client.users       # paginated
users = client.users.all   # non-paginated

users.each do |user|
  user.first_name  # => "John"
  user.last_name  # => "Doe"
end

# Get User
user = client.users.get(1)

user.first_name  # => "John"
user.last_name  # => "Doe"

# Create a User
user = client.users.create(
  first_name: "John",
  last_name: "Doe"
)

user.id  # => 1
user.first_name  # => "John"
user.last_name  # => "Doe"

# Update a User
user = client.users.update(1, first_name: "Jane")

user.first_name  # => "Jane"

# Authenticate a User
user = client.users.auth(email: "john.doe@kentaa.nl", password: "secret")

user.id  # => 1
user.first_name  # => "John"
user.last_name  # => "Doe"

See also the Kentaa API docs and Kentaa::Api::Resources::User for all available properties.

User avatar

# Get the User avatar
avatar = user.avatar

avatar.avatar_url  # => "https://cdn.kentaa.nl/avatars/avatar/1/thumb_8ce42aeb3bbb1b4964e621b42691f13d4dfa3f21.jpg"

# Create / update the User avatar
avatar = user.avatar.create(
  io: File.open("photo.jpeg"),
  content_type: "image/jpeg"
)

avatar.avatar_url  # => "https://cdn.kentaa.nl/avatars/avatar/1/thumb_8ce42aeb3bbb1b4964e621b42691f13d4dfa3f21.jpg"

# Delete the User avatar
user.avatar.delete

See also the Kentaa API docs and Kentaa::Api::Resources::Avatar for all available properties.

Pagination

All List actions return paginated results in an Enumerable object. The default page size is 25, but you can can customize this by setting the per_page parameter.

actions = client.actions(per_page: 100)

actions.each do |action|
  action.title  # => "Lorem ipsum"
  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
end

You can iterate through the pages using the .next method and checking the result. For example:

actions = client.actions

loop do
  actions.each do |action|
    # Do something with actions
  end

  actions = actions.next
  break if actions.nil?
end

The all method on the endpoint returns a lazy Enumerator and will automatically iterate through all pages and retrieve the requested data.

actions = client.actions.all

actions.each do |action|
  action.title  # => "Lorem ipsum"
  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
end

See Kentaa::Api::Resources::List for all available pagination methods.

Error handling

All responses that are not HTTP status 20x will result in a Kentaa::Api::RequestError.

begin
  client.actions.get("invalid")
rescue Kentaa::Api::RequestError => e
  e.message  # => "404: Requested resource was not found."
  e.http_code  # => 404
  e.errors  # => Array[Kentaa::Api::Resources::Error]
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/KentaaNL/kentaa-api.

License

The gem is available as open source under the terms of the MIT License.