EventbriteSdk

Code Climate Issue Count Build Status Test Coverage Dependency Status Gem Version

Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/eventbrite_sdk. To experiment with that code, run bin/console for an interactive prompt.

Installation

Add this line to your application's Gemfile:

gem 'eventbrite_sdk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install eventbrite_sdk

Usage

The library needs to be configured with your account's personal OAuth token which is available in your [App Management][app management] page. Assign it's value to EventbriteSDK.token and the library will send it along automatically with every request.

Basic usage for creating/retrieving/updating/publishing an event:


EventbriteSDK.token = "TOKEN"

# create an event draft
your_event = EventbriteSDK::Event.build('name.html' => 'Event Name', 'start.utc' => '2018-01-31T13:00:00Z', 'start.timezone' => 'America/Los_Angeles', 'end.utc' => '2018-02-01T13:00:00Z', 'end.timezone' => 'America/Los_Angeles', 'currency' => 'USD')

your_event.save
# => true

# retrieve your event
your_event

# retrieve one field on the object
your_event.id

# retrieve any event by id
EventbriteSDK::Event.retrieve(id: 20955468370)

# update the event
your_event.assign_attributes('name.html' => 'A new name', 'description.html' => 'A new description')

your_event.save
# =>true

# add ticket classes to the event
event_ticket = EventbriteSDK::TicketClass.new(event_id: your_event.id)
event_ticket.assign_attributes('name'=>'Ticket Name', 'cost'=>'USD,3400', 'quantity_total'=>'378')

event_ticket.save

# to see if the event is 'dirty' (i.e. has unsaved changes)
your_event.changed?
# =>true

# save the changes
your_event.save

# publish the event
your_event.publish

Navigating paginated responses:


EventbriteSDK.token = "TOKEN"

# one feature of the Eventbrite API is that you can pass in the string 'me' in place of a 
# user id and it will evaluate to the id of the user associated with the oauth token.

# fetch a new user record using the Eventbrite user id
user = EventbriteSDK::User.retrieve(id: 163054428874)

# get one page of your events
events = user.owned_events.page(2)

# not providing a page number will default to page one
events = user.owned_events.page(1) => events = user.owned_events

# events is now an enumerable object that you can access using bracket notation or first/last
events.first => events[0]
events.last => events[-1]

# endpoints that support continuations: will be inferred from the current payload
# you can tell if a paginated result set supports continuations by checking for a non-nil #continuation

example.continuation #=> "dGhpcyBpcyBwYWdlIDE"

# you can continue until the example returns nil, which means there are no more items
example.continue

# you can also provide a token if you choose to do so
example.continue(continuation_token: 'my_token')

Use #retrieve to build up arbitrary queries


# For example, to use the 'status' parameter seen here: https://www.eventbrite.com/developer/v3/endpoints/events/#ebapi-id78

user = EventbriteSDK::User.retrieve(id: 163054428874)
user.owned_events.retrieve(query: { status: 'live' })

Construct endpoint paths:


EventbriteSDK.token = "TOKEN"

# access this endpoint www.eventbriteapi.com/v3/events/:id/ticket_classes/:id/
ticket = EventbriteSDK::TicketClass.retrieve(event_id: 20928651159, id: 43892783)

Use expansions


EventbriteSDK.token = "TOKEN"

# get an order with attendees expanded

order = EventbriteSDK::Order.retrieve(id: id, expand: [:attendees])

# include multiple expansions in one request

order = EventbriteSDK::Order.retrieve(id: id, expand: [:attendees, :event])

Per-request Configuration

For apps that need to use multiple tokens during the lifetime of a process, it is possible to set a per-request token:


# Retrieving

EventbriteSDK::Order.retrieve(
  id: id,
  api_token: YOUR_REQUEST_TOKEN
)

# Retrieving lists

events = EventbriteSDK::User.me.owned_events.page(1, api_token: YOUR_REQUEST_TOKEN)

events.next_page(api_token: YOUR_REQUEST_TOKEN)

# Saving/Deleting

event.save(api_token: YOUR_REQUEST_TOKEN)

order.delete(api_token: YOUR_REQUEST_TOKEN)

If you forget to provide the api_token key and EventbriteSDK.token is set, the request will fall-back on the global token for the action called.

Shallow resource list endpoints

Some paginated lists are available at the base of the resource url, webhooks and categories for example. The resources that have this trait will include the Operations::List module


# Retrieving

categories = EventbriteSDK::Category.list.page(1) #=> GET /v3/categories/?page=1
webhooks = EventbriteSDK::Webhook.list.page(1) #=> GET /v3/webhooks/?page=1

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/eventbrite/eventbrite-sdk-ruby.

License

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