mirror of
https://github.com/ngrok/ngrok-api-ruby.git
synced 2026-05-17 16:50:40 +00:00
Kyle Wenholz
95 lines
2.4 KiB
Plaintext
95 lines
2.4 KiB
Plaintext
# 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
|
|
```
|