nationbuilder-rb¶ ↑
A Ruby client for the NationBuilder
API.
Installing¶ ↑
To install this gem to your current gemset, run:
$ gem install nationbuilder-rb
Or, add this to your gemfile:
gem 'nationbuilder-rb', require: 'nationbuilder'
Creating a client¶ ↑
Require the gem:
require 'nationbuilder'
Then, create a client by specifying the name of your nation and your API token:
client = NationBuilder::Client.new('my_nation_name', 'my_api_token', retries: 8)
The retries
parameter specifies the maximum number of retries to attempt when the client is rate limited. This uses an exponential backoff strategy. The default is 8
.
Calling the API¶ ↑
The primary method for calling the NationBuilder
API in nationbuilder-rb
is the #call
method, used on a client. The #call
method takes three parameters: the name of the endpoint, the name of the method, and an optional hash containing arguments for the method.
Examples¶ ↑
Fetching a person¶ ↑
client.call(:people, :show, id: 15)
Creating a person¶ ↑
params = { person: { email: "bob@example.com", last_name: "Smith", first_name: "Bob" } } client.call(:people, :create, params)
Destroying a person¶ ↑
client.call(:people, :destroy, id: 15)
Pagination¶ ↑
A call can be paginated by creating a new instance of the Paginator
class. This takes two parameters: the client and the response of the call to be paginated.
response = client.call(:people, :index) paginated = NationBuilder::Paginator.new(client, response) page1 = paginated page2 = page1.next page3 = page2.next
Methods #next
and #prev
return the results of the next or previous page of results, nil if none. #next?
and #prev?
alert the caller to whether other pages of results exist. The JSON results of a page can be accessed by calling #body
on a page: in the above example, page1.body
returns the same hash as response
.
Documentation¶ ↑
This gem includes a command line utility that prints out all covered endpoints, methods, and parameters. To see documentation for a single endpoint, run:
$ nbdoc ENDPOINT_NAME
To see all documentation, don't provide a endpoint name:
$ nbdoc
Example¶ ↑
$ nbdoc basic_pages ===================== Endpoint: basic_pages ===================== Method: index Description: Shows a list of the basic pages in the system Required parameters: site_slug Method: create Description: Creates a basic page for a site Required parameters: site_slug ...
Modifying the underlying HTTPClient¶ ↑
The NationBuilder::Client
object can use a provided HTTPClient object if you need some customizations, such as to enable logging, change TLS settings, or add a proxy. For example to force a proxy for all traffic:
httpclient = HTTPClient.new('http://myproxy:8080') client = NationBuilder::Client.new(nation_builder_slug, nation_builder_auth_token, retries: 8, http_client: httpclient)
Development¶ ↑
To update the API specification that powers this client, first make the appropriate updates to the api_spec repository. Once the changes have been merged to api_spec's master branch, run the update_subtree.sh
script in the root directory of this project to copy over the changes.