ruby-sdk
Official Ruby Client for the PortaText API.
Documentation
- The endpoint tests should also serve as good doucmentation on how to use the API.
- General PortaText documentation (including the REST API) can be found at the PortaText wiki.
Installing
Add this library to your Gemfile.
gem 'portatext'
Basic use
Getting a client instance
The first thing is to get a Client instance, for example the Net::HTTP implementation:
require 'portatext'
client = PortaText::Client::HttpClient.new
(Optional) Set your logger
You can optionally set a Logger compatible logger:
client.logger = my_logger
By default, the client will use a logger pointing to /dev/null
Authenticating
You can authenticate to the endpoints by using your API key or your username/password. This translates to either doing this:
client.api_key = api_key
Or this:
client.credentials = [username, password]
When you specify a username and password instead of an api key, the sdk will automatically login and get a session token when needed.
Using the endpoints
All the API commands can be found in the command/api directory. The client offers a way to instantiate them by just calling them by their name.
Quick example
As an example, to create a template, you would do:
result = client
.templates # Get an instance of the Templates endpoint.
.text('The text of my template')
.description('My first template')
.name('template1')
.post # Call the Templates endpoint with a POST.
To get a template by id:
result = client.templates.id(45).get
Or, to get all the templates:
result = client.templates.get
The result
After calling an endpoint, one of two things can happen:
- A PortaText Exception is raised.
- A Result instance is returned.
Also, when possible, your PortaText exception will contain a Result
object that
can be retrieved by using the result
accessor on the exception. This is usually useful for the
ClientError exception, where
you will be able to see if a field was missing or different than what was expected.
Testing for success
if result.success?
...
end
Getting error strings back from the server
if !result.errors.nil?
result.errors.each do |e|
puts e
end
end
Getting data back from the server
if result.success
data = result.data
end
Developers
This project uses rake. Current tasks include:
- test: Runs MiniTests.
- rubocop: Runs RuboCop.
- default: This is the default task, and will run all the other tasks.
Running a rake task
To run a task, just do:
rake test
Contributing
To contribute:
- Make sure you open a concise and short pull request.
- Throw in any needed unit tests to accomodate the new code or the changes involved.
- Run
rake
and make sure everything is ok before submitting the pull request (make rubocop happy). - Your code must comply with the GitHub ruby style.
- If your code is accepted, it will belong to PortaText and will be published under the Apache2 License.
License
The source code is released under Apache 2 License.
Check LICENSE file for more information.