Class: ApiAdaptor::Base

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/api_adaptor/base.rb

Overview

Base class for building API-specific clients.

Provides common functionality for JSON API clients including HTTP method delegation, URL construction, and pagination support. Subclass this to create clients for specific APIs.

Examples:

Creating a custom API client

class MyApiClient < ApiAdaptor::Base
  def initialize
    super("https://api.example.com", bearer_token: "abc123")
  end

  def get_user(id)
    get_json("/users/#{id}")
  end

  def list_posts(page: 1)
    get_list("/posts?page=#{page}")
  end
end

Using default options

ApiAdaptor::Base.default_options = { timeout: 10 }
client = MyApiClient.new  # Inherits 10-second timeout

See Also:

  • for underlying HTTP client options

Defined Under Namespace

Classes: InvalidAPIURL

Class Attribute Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(endpoint_url = nil, options = {}) ⇒ Base

Initializes a new API client

Examples:

Basic initialization

client = Base.new("https://api.example.com")

With authentication

client = Base.new("https://api.example.com", bearer_token: "abc123")

Parameters:

  • endpoint_url (String, nil) (defaults to: nil) —

    Base URL for the API

  • options (Hash) (defaults to: {}) —

    Configuration options (see JSONClient#initialize for details)

Raises:



161
162
163
164
165
166
167
168
169
 
# File 'lib/api_adaptor/base.rb', line 161

def initialize(endpoint_url = nil, options = {})
  options[:endpoint_url] = endpoint_url
  raise InvalidAPIURL if !endpoint_url.nil? && endpoint_url !~ URI::RFC3986_Parser::RFC3986_URI

  base_options = { logger: ApiAdaptor::Base.logger }
  default_options = base_options.merge(ApiAdaptor::Base.default_options || {})
  @options = default_options.merge(options)
  self.endpoint = options[:endpoint_url]
end

Class Attribute Details

.default_options ⇒ Hash?

Default options merged into all Base instances

Returns:

  • (Hash, nil) —

    Default options hash



139
140
141
 
# File 'lib/api_adaptor/base.rb', line 139

def default_options
  @default_options
end

.logger ⇒ Logger

Returns the default logger for Base instances

Returns:

  • (Logger) —

    Logger instance (defaults to NullLogger)



145
146
147
 
# File 'lib/api_adaptor/base.rb', line 145

def self.logger
  @logger ||= ApiAdaptor::NullLogger.new
end

Instance Attribute Details

#options ⇒ Hash (readonly)

Returns The client configuration options.

Returns:

  • (Hash) —

    The client configuration options



128
129
130
 
# File 'lib/api_adaptor/base.rb', line 128

def options
  @options
end

Instance Method Details

#client ⇒ JSONClient

Returns the underlying JSONClient instance, creating it if necessary

Returns:

  • (JSONClient) —

    The HTTP client instance



44
45
46
 
# File 'lib/api_adaptor/base.rb', line 44

def client
  @client ||= create_client
end

#create_client ⇒ JSONClient

Creates a new JSONClient with the configured options

Returns:

  • (JSONClient) —

    A new HTTP client instance



51
52
53
 
# File 'lib/api_adaptor/base.rb', line 51

def create_client
  ApiAdaptor::JsonClient.new(options)
end

#delete_json(url, params = {}) ⇒ Response

Performs a DELETE request

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Optional data to send as JSON

Returns:

See Also:

  • JSONClient#delete_json


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#get_json(url) {|Hash| ... } ⇒ Response, Object

Performs a GET request and parses JSON response

Parameters:

  • url (String) —

    The URL to request

Yields:

  • (Hash) —

    The parsed JSON response

Returns:

  • (Response, Object) —

    Response object or yielded value

See Also:

  • JSONClient#get_json


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#get_list(url) ⇒ ListResponse

Performs a GET request and wraps the response in a ListResponse

Examples:

list = client.get_list("/posts?page=1")
list.results       # => Array of items
list.current_page  # => 1
list.total_pages   # => 10

Parameters:

  • url (String) —

    The URL to request

Returns:



196
197
198
199
200
 
# File 'lib/api_adaptor/base.rb', line 196

def get_list(url)
  get_json(url) do |r|
    ApiAdaptor::ListResponse.new(r, self)
  end
end

#get_raw(url) ⇒ RestClient::Response

Performs a GET request and returns raw response

Parameters:

  • url (String) —

    The URL to request

Returns:

  • (RestClient::Response) —

    Raw response object

See Also:

  • JSONClient#get_raw


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#get_raw!(url) ⇒ RestClient::Response

Performs a GET request and returns raw response, raising on errors

Parameters:

  • url (String) —

    The URL to request

Returns:

  • (RestClient::Response) —

    Raw response object

Raises:

See Also:

  • JSONClient#get_raw!


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#patch_json(url, params = {}) ⇒ Response

Performs a PATCH request with JSON body

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Data to send as JSON

Returns:

See Also:

  • JSONClient#patch_json


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#post_json(url, params = {}) ⇒ Response

Performs a POST request with JSON body

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Data to send as JSON

Returns:

See Also:

  • JSONClient#post_json


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#post_multipart(url, params = {}) ⇒ Response

Performs a POST request with multipart/form-data

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Multipart form data

Returns:

See Also:

  • JSONClient#post_multipart


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#put_json(url, params = {}) ⇒ Response

Performs a PUT request with JSON body

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Data to send as JSON

Returns:

See Also:

  • JSONClient#put_json


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#put_multipart(url, params = {}) ⇒ Response

Performs a PUT request with multipart/form-data

Parameters:

  • url (String) —

    The URL to request

  • params (Hash) (defaults to: {}) —

    Multipart form data

Returns:

See Also:

  • JSONClient#put_multipart


116
117
118
119
120
121
122
123
124
125
 
# File 'lib/api_adaptor/base.rb', line 116

def_delegators :client,
:get_json,
:post_json,
:put_json,
:patch_json,
:delete_json,
:get_raw,
:get_raw!,
:put_multipart,
:post_multipart

#url_for_slug(slug, options = {}) ⇒ String

Constructs a URL for a given slug with query parameters

Examples:

url_for_slug("users/123", include: "posts")
# => "https://api.example.com/users/123.json?include=posts"

Parameters:

  • slug (String) —

    The API endpoint slug

  • options (Hash) (defaults to: {}) —

    Query parameters to append

Returns:

  • (String) —

    Full URL with .json extension and query string



181
182
183
 
# File 'lib/api_adaptor/base.rb', line 181

def url_for_slug(slug, options = {})
  "#{base_url}/#{slug}.json#{query_string(options)}"
end