Class: Recurly::API

Inherits:
Object
  • Object
show all
Extended by:
Net::HTTPAdapter
Defined in:
lib/recurly/api.rb,
lib/recurly/api/errors.rb,
lib/recurly/api/net_http_adapter.rb

Overview

The API class handles all requests to the Recurly API. While most of its functionality is leveraged by the Resource class, it can be used directly, as well.

Requests are made with methods named after the four main HTTP verbs recognized by the Recurly API.

Examples:

Recurly::API.get 'accounts'             # => #<Net::HTTPOK ...>
Recurly::API.post 'accounts', xml_body  # => #<Net::HTTPCreated ...>
Recurly::API.put 'accounts/1', xml_body # => #<Net::HTTPOK ...>
Recurly::API.delete 'accounts/1'        # => #<Net::HTTPNoContent ...>

Defined Under Namespace

Modules: Net Classes: BadRequest, ClientError, Forbidden, GatewayError, InternalServerError, MethodNotAllowed, NotAcceptable, NotFound, NotModified, PaymentRequired, PreconditionFailed, Redirection, ResponseError, ServerError, ServiceUnavailable, Unauthorized, UnprocessableEntity, UnsupportedMediaType

Constant Summary

RECURLY_API_VERSION = 
'2.10'
FORMATS = 
Helper.hash_with_indifferent_read_access(
  'pdf' => 'application/pdf',
  'xml' => 'application/xml'
)
ERRORS =

Error mapping by status code.

Hash.new { |hash, code|
  unless hash.key? code
    case code
      when 400...500 then ClientError
      when 500...600 then ServerError
      else                ResponseError
    end
  end
}.update(
  304 => NotModified,
  400 => BadRequest,
  401 => Unauthorized,
  402 => PaymentRequired,
  403 => Forbidden,
  404 => NotFound,
  406 => NotAcceptable,
  412 => PreconditionFailed,
  415 => UnsupportedMediaType,
  422 => UnprocessableEntity,
  500 => InternalServerError,
  502 => GatewayError,
  503 => ServiceUnavailable
).freeze
@@base_uri = 
"https://api.recurly.com/v2/"
@@valid_domains = 
[".recurly.com"]

Instance Attribute Summary

Attributes included from Net::HTTPAdapter

#net_http

Class Method Summary collapse

Class Method Details

.accept_language ⇒ String?

Returns Accept-Language header value

Returns:

  • (String, nil) —

    Accept-Language header value



35
36
37
 
# File 'lib/recurly/api.rb', line 35

def accept_language
  headers['Accept-Language']
end

.accept_language=(language) ⇒ Object

Parameters:

  • language (String) —

    Accept-Language header value



40
41
42
 
# File 'lib/recurly/api.rb', line 40

def accept_language=(language)
  headers['Accept-Language'] = language
end

.base_uri ⇒ URI::Generic

Returns:

  • (URI::Generic) 


75
76
77
 
# File 'lib/recurly/api.rb', line 75

def base_uri
  URI.parse @@base_uri.sub('api', Recurly.subdomain)
end

.delete(uri, body = nil, options = {}) ⇒ Net::HTTPNoContent, Net::HTTPResponse

Returns:

  • (Net::HTTPNoContent, Net::HTTPResponse)

Raises:



70
71
72
 
# File 'lib/recurly/api.rb', line 70

def delete uri, body = nil, options = {}
  request :delete, uri, options
end

.get(uri, params = {}, options = {}) ⇒ Net::HTTPOK, Net::HTTPResponse

Returns:

  • (Net::HTTPOK, Net::HTTPResponse)

Raises:



52
53
54
 
# File 'lib/recurly/api.rb', line 52

def get uri, params = {}, options = {}
  request :get, uri, { :params => params || {} }.merge(options)
end

.head(uri, params = {}, options = {}) ⇒ Net::HTTPOK, Net::HTTPResponse

Returns:

  • (Net::HTTPOK, Net::HTTPResponse)

Raises:



46
47
48
 
# File 'lib/recurly/api.rb', line 46

def head uri, params = {}, options = {}
  request :head, uri, { :params => params || {} }.merge(options)
end

.headers ⇒ Hash{String => String}

Additional HTTP headers sent with each API call

Returns:

  • (Hash{String => String}) 


30
31
32
 
# File 'lib/recurly/api.rb', line 30

def headers
  @headers ||= { 'Accept' => accept, 'User-Agent' => user_agent, 'X-Api-Version' => RECURLY_API_VERSION }
end

.post(uri, body = nil, options = {}) ⇒ Net::HTTPCreated, Net::HTTPResponse

Returns:

  • (Net::HTTPCreated, Net::HTTPResponse)

Raises:



58
59
60
 
# File 'lib/recurly/api.rb', line 58

def post uri, body = nil, options = {}
  request :post, uri, { :body => body.to_s }.merge(options)
end

.put(uri, body = nil, options = {}) ⇒ Net::HTTPOK, Net::HTTPResponse

Returns:

  • (Net::HTTPOK, Net::HTTPResponse)

Raises:



64
65
66
 
# File 'lib/recurly/api.rb', line 64

def put uri, body = nil, options = {}
  request :put, uri, { :body => body.to_s }.merge(options)
end

.user_agent ⇒ String

Returns:

  • (String) 


87
88
89
 
# File 'lib/recurly/api.rb', line 87

def user_agent
  "Recurly/#{Version}; #{RUBY_DESCRIPTION}"
end

.validate_uri!(uri) ⇒ Object 



79
80
81
82
83
84
 
# File 'lib/recurly/api.rb', line 79

def validate_uri!(uri)
  domain = @@valid_domains.detect { |d| uri.host.end_with?(d) }
  unless domain
    raise ArgumentError, "URI #{uri} is invalid. You may only make requests to a Recurly domain."
  end
end