Ruby Library v1

View Repo

The Flowroute Ruby Library v1 provides methods for interacting with Numbers v1 of the Flowroute API.

Requirements


Installation

  1. First, start a shell session and clone the SDK:

    via HTTPS:

    git clone https://github.com/flowroute/flowroute-numbers-ruby.git
                        

    via SSH:

    git@github.com:flowroute/flowroute-numbers-ruby.git
                        
  2. Switch to the newly-created flowroute-numbers-ruby directory and run the following to build the Flowroute gem:

    gem build flowroute_numbers.gemspec
                        

    This version of the library has been tested with Ruby 2.5.0 for Mac OS X. To see which version of ruby is installed on your machine, run the following:

    ruby --version
    
  3. Once built, run the following to install the gem in the current directory:

    gem install flowroute_numbers-1.0.gem
    

Usage

In Flowroute's approach to building the Numbers (v1) API wrapper, HTTP requests are handled by controllers, which contain the methods used to perform tasks with the Ruby SDK.

Controllers

  • PurchasablePhoneNumbersController

    Contains all of the methods necessary to search through Flowroute's phone number inventory.

  • TelephoneNumbersController

    Contains all of the methods necessary to purchase a new phone number and manage your owned phone number inventory.

  • InboundRoutesController

    Contains the methods required to create new routes and view your current routes.

    • list() - List existing inbound routes from your account
    • create_new_route() - Create a new inbound route that can then be assigned as either a primary or failover route for a phone number

The following shows an example of a single Ruby file that imports and instantiates all three Controllers:

require 'flowroute_numbers'
require 'rubygems'

pnc = FlowrouteNumbers::PurchasablePhoneNumbersController.new()
tnc = FlowrouteNumbers::TelephoneNumbersController.new()
irc = FlowrouteNumbers::InboundRoutesController.new()

            

Credentials

In your Ruby file, replace AccessKey and SecretKey with your API credentials from the Flowroute Manager.

#Pass your API credentials
FlowrouteNumbers::Configuration.username = 'AccessKey'
FlowrouteNumbers::Configuration.password = 'SecretKey'  

            

Methods

list_available_np_as()

The method accepts the limit and page parameters which you can learn more about in the API reference. The following example limits the number of NPAs returned to 2:

#List Available NPAs
response = pnc.list_available_np_as(limit=2)

            
Example Response
{
 "npas": {
   "201": {
     "nxxs": "/v1/available-tns/npanxxs/?npa=201",
    "tns": "/v1/available-tns/tns/?npa=201"
   },
   "202": {
      "nxxs": "/v1/available-tns/npanxxs/?npa=202",
      "tns": "/v1/available-tns/tns/?npa=202"
    }
  },
  "links": {
  "next": "/v1/available-tns/npas/?limit=2&page=2"
  }
}
            
            
list_area_and_exchange()

The method accepts the limit, npa, and page parameters which you can learn more about in the API reference. The following example sets the limit to 2, the npa to 206, and the display page to 2:

#List NPA and NXX
response = pnc.list_area_and_exchange(limit=2, npa=206,page=2)

            
Example Response

Results are returned in numerical order, starting with the lowest NPA number. The npaxxs parameter variable is formatted as a combination of the NPA and NXX. In the following example, 206258 is the combination of NPA 206 and NXX 258.

{
"npanxxs": {
  "206258": {
    "tns": "/v1/available-tns/tns/?npa=206&nxx=258"
   },
   "206238": {
     "tns": "/v1/available-tns/tns/?npa=206&nxx=238"
    }
  },
  "links": {
    "prev": "/v1/available-tns/npanxxs/?npa=206&limit=2&page=1",
    "next": "/v1/available-tns/npanxxs/?npa=206&limit=2&page=3"
 }
}
            
            
search()

The search() method is the most robust option for searching through Flowroute's purchasable phone number inventory. It allows you to search by NPA, NXX, Ratecenter, State, and/or TN (telephone number). The method accepts the limit, npa, nxx, and page parameters which you can learn more about in the API reference.

In the following example, a search request sets the limit to 1, the npa to 206, the nxx to 743, to display page 2, the ratecenter to "seattle", the state to "wa", and the tn to None.

#Search
response = pnc.search(limit=1,npa=206,nxx=743,page=1,ratecenter='seattle',state='wa',tn=None)

            
Example Response
{
"links": {
  "next": "/v1/available-tns/tns/?npa=206&nxx=743&state=wa&ratecenter=seattle&limit=1&page=2"
 },
 "tns": {
    "12067439178": {
     "initial_cost": "1.00",
     "monthly_cost": "1.25",
    "state": "WA",
    "ratecenter": "SEATTLE",
    "billing_methods": [
     "METERED"
   ]
   }
     }
}
            
            
purchase()

The purchase() method is used to purchase a telephone number from Flowroute's inventory. The method accepts the billing_method (within the BillingMethod object) and telephone_number parameters which you can learn more about in the API reference.

#Purchase a Telephone Number
response = tnc.purchase(billing="METERED", number="12066417744")

            
Example Response

For a successful purchase, the API returns an empty line. No other success message is displayed.

201 Created
{ }
            
            
list_account_telephone_numbers()

The method accepts the limit, page, and pattern parameters which you can learn more about in the API reference. The following example sets the limit to 5, the page to 2, and the search pattern to 206:

#List Account Telephone Numbers
response = tnc.list_account_telephone_numbers(limit=5,page=2,pattern=206)

            
Example Response
{
  "links": {
    "prev": "/v1/tns/?limit=1&page=1",
    "next": "/v1/tns/?limit=1&page=3"
 },
  "tns": {
    "12062092844": {
      "routes": [
     {
       "type": "SIP-REG",
       "name": "sip-reg"
     },
     {
       "type": "SIP-REG",
       "name": "sip-reg"
     }
   ],
   "billing_method": "METERED",
   "detail": "/v1/tns/16476998778"
 }
}
}
            
            
telephone_number_details()

The method accepts the telephone_number parameter which you can learn more about in the API reference. In the following example, details are requested for the telephone number just purchased using the purchase method.

#Telephone Number Details
response = tnc.telephone_number_details(16476998778)

            
Example Response
{
 "routes": [
  {
     "type": "SIP-REG",
     "name": "sip-reg"
   },
    {
     "type": "SIP-REG",
     "name": "sip-reg"
   }
 ],
  "billing_method": "METERED"
}
            
            

update()

The method accepts the routes and telephone_number parameters which you can learn more about in the API reference.

#Update Telephone Number Routes
rtes = [Route(name='sip-reg'), Route(name='ea4f4056663e27b082999689982e4723')]
response = tnc.update(number=16476998778, routes=rtes)

            
Example Response

An empty line is returned for a successful update. No other message is returned. You can verify that the routes were changed by calling the list method.

204 No Content
''
            
            
list()

The method accepts the limit, page, and pattern parameters which you can learn more about in the API reference.

#List Routes
response = irc.list(limit=4, page=None)

            
Example Response
{
routes:
 {
   HOSTroute1:
        {
            type: HOST
            value => 24.239.23.40:5060
        }
   PSTNroute1:
        {
            type: PSTN
            value: 178
        }
    URIroute1:
        {
            type: URI
            value: sip:16476998778@215.122.69.152:5060
        }
    sip-reg:
        {
            type: SIP-REG
            value: sip-reg
        }
 }
}
            
            
create_new_route()

The method accepts the route_name, type, and value parameters which you can learn more about in the API reference. The following example shows the creation of three new routes:

#Create New Routes
response = irc.create_new_route(route_name='PSTNroute1',mtype='PSTN',value='16476998778')
response = irc.create_new_route(route_name='HOSTroute1',mtype='HOST',value='24.239.23.40:5060')
response = irc.create_new_route(route_name='URIroute1',mtype='URI',value='sip:16476998778@215.122.69.152:5060')

            
Example Response

An empty string ('') is returned for each successfully created route; no other code or message is returned. An error encountered for a specific irc.create_new_route() line does not prevent the other routes from being created.

201 Created
' '