Ruby client for Cisco Spark.
Add this line to your application's Gemfile:
gem 'cisco_spark'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cisco_spark
Configuration can be done in an initializer on app boot. An API key or users OAuth token is required to make any API requests.
API key example:
CiscoSpark.configure do |config|
config.api_key = 'YOUR KEY'
end
If you are using OAuth token you can wrap API operaions in a block, all API calls within the block will then use that token.
OAuth token example:
CiscoSpark.with_token('OAuth token') do
users_rooms = CiscoSpark::Room.fetch_all
end
All models have methods to interact with the API and parse response data.
Inlcuded models:
CiscoSpark::Person
CiscoSpark::Room
CiscoSpark::Membership
CiscoSpark::Message
CiscoSpark::Team
CiscoSpark::TeamMembership
CiscoSpark::Webhook
You can call all the following methods on any of these models
Fetches all records for a given model, returns a CiscoSpark::Collection
Accepts any parameters that the API allows.
rooms = CiscoSpark::Room.fetch_all(max: 5)
=> #<CiscoSpark::Collection>
Fetches a single record for the given resource ID, returns an instance Accepts any parameters that the API allows.
room = CiscoSpark::Room.fetch('Y2lzY...', show_sip_address: true)
=> #<CiscoSpark::Room>
Creates a resource with given attribues, returns an instance Accepts any parameters that the API allows.
room = CiscoSpark::Room.create(title: 'Ruby Room')
=> #<CiscoSpark::Room>
Updates a resource with given attribues, returns an instance Accepts any parameters that the API allows.
room = CiscoSpark::Room.update('Y2lzY...', title: 'Groovey Ruby Room')
=> #<CiscoSpark::Room>
Destroys a resource with the given ID, returns an boolean to indicate success Accepts any parameters that the API allows.
room = CiscoSpark::Room.destroy('Y2lzY...')
=> true
Parses a valid JSON string or a ruby hash/array into a collection of models. This is useful for processing data recieved from a webhook etc.
json_string = '{"items": [{ "id": "Y2lzY...", "key": "value" }]}'
rooms = CiscoSpark::Room.parse_collection(json_string)
=> #<CiscoSpark::Collection>
Parses a valid JSON string or a ruby hash/array into a model. This is useful for processing data recieved from a webhook etc.
json_string = '{ "id": "Y2lzY...", "key": "value" }'
room = CiscoSpark::Room.parse(json_string)
=> #<CiscoSpark::Room>
Creates a new instance of the model with given attributes
room = CiscoSpark::Room.new(title: 'New room')
=> #<CiscoSpark::Room>
You can call persist on an instance to create or update it through the API.
If the instance already has an ID a PUT
will be made to update the mutable attributes
room = CiscoSpark::Room.new(title: 'New room')
room.persist
=> #<CiscoSpark::Room>
You can call fetch on an instance fetch or refresh an instance
room = CiscoSpark::Room.new(id: 'Y2lzY...')
room.fetch
=> #<CiscoSpark::Room>
You can call destroy on an instance to destroy it through the API
room = CiscoSpark::Room.new(id: 'Y2lzY...')
room.destroy
=> true
Convert a model instance into a hash
room = CiscoSpark::Room.fetch('Y2lzY...')
room.to_h
=> Hash
Search all people by email,
people = CiscoSpark::Person.all_by_email('nickpmaher@gmail.com', max: 5)
=> #<CiscoSpark::Collection>
Search all people by display name
people = CiscoSpark::Person.all_by_name('Nick', max: 5)
=> #<CiscoSpark::Collection>
Get all memberships for person
person = CiscoSpark::Person.new(id: 'Y2lz...')
person.memberships(max: 5)
=> #<CiscoSpark::Collection>
Get all memberships for room
room = CiscoSpark::Room.new(id: 'Y3de...')
room.memberships(max: 5)
=> #<CiscoSpark::Collection>
Get all messages for room
room = CiscoSpark::Room.new(id: 'Y3de...')
room.messages(max: 5)
=> #<CiscoSpark::Collection>
Get all message before a given message, accepts a CiscoSpark::Message
or a message ID
room.all_before_message('Y3de...', max: 5)
=> #<CiscoSpark::Collection>
Get all message before a given time, accepts a DateTime
or a string
room.messages_before(DateTime.now, max: 5)
=> #<CiscoSpark::Collection>
Send a message to the room
message = CiscoSpark::Message.new(text: 'Hello Spark')
room = CiscoSpark::Room.new(id: 'Y3de...')
room.send_message(message)
=> #<CiscoSpark::Message>
Creates a new membership to the room for a given person
person = CiscoSpark::Person.fetch('Y2lz')
room = CiscoSpark::Room.new(id: 'Y3de...')
room.add_person(person)
=> #<CiscoSpark::Membership>
Returns the person for this membership
Returns the room this membership belongs to
Returns the person that sent this message
Returns the person that the message was sent to
Get all memberships for team
team = CiscoSpark::Team.new(id: 'Y3de...')
team.memberships(max: 5)
=> #<CiscoSpark::Collection>
Creates a new membership to the team for a given person
person = CiscoSpark::Person.fetch('Y2lz')
team = CiscoSpark::Team.new(id: 'Y3de...')
team.add_person(person)
=> #<CiscoSpark::TeamMembership>
Returns the person for this membership
Returns the team this membership belongs to
Wraps a collection of models. Responds to all enumerable methods e.g. first
, map
, each
etc...
Call next
on a collection to load the next page of data
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
.
Bug reports and pull requests are welcome on GitHub at https://github.com/NGMarmaduke/cisco_spark-ruby.
The gem is available as open source under the terms of the MIT License.