License Gem Version Yard Docs

Build Status Coverage Status Code Climate Issue Count Inline docs

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:

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.