# ngrok-api

This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it
easier to consume in Ruby.

## Installation

This library is published on [Rubygems](https://rubygems.org/gems/ngrok-api)

```ruby
gem install ngrok-api
```

## Quickstart

Please consult the [documentation](https://ruby-api.docs.ngrok.com) for additional examples.

```ruby
require 'ngrokapi'
client = NgrokAPI::Client.new(api_key: '<API KEY>')

# Get an instance of the api_keys client and list all API keys
keys_client = client.api_keys
keys_client.list
```

## Automatic Paging

The ngrok API pages all list resources but this library abstracts that away
from you. All response objects from any ``list`` or ``list!`` methods return an object that
implements an ``each`` method which will automatically fetch additional
pages for you.

```ruby
require 'ngrokapi'
client = NgrokAPI::Client.new(api_key: '<API KEY>')

# list all api keys, transparently fetching additional
# pages for you if necessary
keys_client = client.api_keys
keys_client.list.each do |key|
  puts(key)
end
```

## Instance Methods

Instance methods like ``update`` and ``delete`` can be invoked on an instance of an
API object itself as well as directly without needing to first fetch the object.

```ruby
require 'ngrokapi'
client = NgrokAPI::Client.new(api_key: '<API KEY>')

# update the metadata of a credential
cred = client.credentials.get(id: 'cr_1kYyunEyn6XHHlqyMBLrj5nxkoz')
cred.update(metadata: {server_name: 'giraffe-1'}.to_json)

# or do it in single call
cred = client.credentials.update(id: 'cr_1kYyunEyn6XHHlqyMBLrj5nxkoz', metadata: {server_name: 'giraffe-1'}.to_json)
```

## Bang Methods
Most methods that interact with the API have a `!` counterpart. It raises an error when
one is returned by the API.

```ruby
require 'ngrokapi'
client = NgrokAPI::Client.new(api_key: '<API KEY>')

# no error raised, even though it's a bad identifier
# the error is simply returned
cred = client.credentials.get(id: 'invalid')

# this raises an NgrokAPI::Error
cred = client.credentials.get!(id: 'invalid')
```

## Error Handling

The ngrok API returns detailed information when an API call fails. Consult the
section on errors for additional details.

```ruby
require 'ngrokapi'
client = NgrokAPI::Client.new(api_key: '<API KEY>')

begin
    client.ip_policies.get!(id: 'invalid')
rescue NgrokAPI::Error => e
    puts(e)
    puts(e.response.to_s)
end
```