Class: X::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
ClientCredentials
Defined in:
lib/x/client.rb

Overview

A client for interacting with the X API

Constant Summary collapse

DEFAULT_BASE_URL =

Default base URL for the X API

"https://api.twitter.com/2/".freeze
DEFAULT_ARRAY_CLASS =

Default class for parsing JSON arrays

Array
DEFAULT_OBJECT_CLASS =

Default class for parsing JSON objects

Hash

Instance Attribute Summary collapse

Attributes included from ClientCredentials

#access_token, #access_token_secret, #api_key, #api_key_secret, #bearer_token, #client_id, #client_secret, #refresh_token

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil, bearer_token: nil, client_id: nil, client_secret: nil, refresh_token: nil, base_url: DEFAULT_BASE_URL, open_timeout: Connection::DEFAULT_OPEN_TIMEOUT, read_timeout: Connection::DEFAULT_READ_TIMEOUT, write_timeout: Connection::DEFAULT_WRITE_TIMEOUT, debug_output: Connection::DEFAULT_DEBUG_OUTPUT, proxy_url: nil, default_array_class: DEFAULT_ARRAY_CLASS, default_object_class: DEFAULT_OBJECT_CLASS, max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS) ⇒ Client

Initialize a new X API client

Examples:

Create a client with bearer token authentication

client = X::Client.new(bearer_token: "your_bearer_token")

Create a client with OAuth 1.0a authentication

client = X::Client.new(api_key: "key", api_key_secret: "secret", access_token: "token", access_token_secret: "token_secret")

Parameters:

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

    the API key for OAuth 1.0a authentication

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

    the API key secret for OAuth 1.0a authentication

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

    the access token for OAuth authentication

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

    the access token secret for OAuth 1.0a authentication

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

    the bearer token for authentication

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

    the OAuth 2.0 client ID

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

    the OAuth 2.0 client secret

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

    the OAuth 2.0 refresh token

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    the base URL for API requests

  • open_timeout (Integer) (defaults to: Connection::DEFAULT_OPEN_TIMEOUT) —

    the timeout for opening connections in seconds

  • read_timeout (Integer) (defaults to: Connection::DEFAULT_READ_TIMEOUT) —

    the timeout for reading responses in seconds

  • write_timeout (Integer) (defaults to: Connection::DEFAULT_WRITE_TIMEOUT) —

    the timeout for writing requests in seconds

  • debug_output (IO) (defaults to: Connection::DEFAULT_DEBUG_OUTPUT) —

    the IO object for debug output

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

    the proxy URL for requests

  • default_array_class (Class) (defaults to: DEFAULT_ARRAY_CLASS) —

    the default class for parsing JSON arrays

  • default_object_class (Class) (defaults to: DEFAULT_OBJECT_CLASS) —

    the default class for parsing JSON objects

  • max_redirects (Integer) (defaults to: RedirectHandler::DEFAULT_MAX_REDIRECTS) —

    the maximum number of redirects to follow



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/x/client.rb', line 84

def initialize(api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
  bearer_token: nil, client_id: nil, client_secret: nil, refresh_token: nil,
  base_url: DEFAULT_BASE_URL,
  open_timeout: Connection::DEFAULT_OPEN_TIMEOUT,
  read_timeout: Connection::DEFAULT_READ_TIMEOUT,
  write_timeout: Connection::DEFAULT_WRITE_TIMEOUT,
  debug_output: Connection::DEFAULT_DEBUG_OUTPUT,
  proxy_url: nil,
  default_array_class: DEFAULT_ARRAY_CLASS,
  default_object_class: DEFAULT_OBJECT_CLASS,
  max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS)
  initialize_credentials(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:,
    client_id:, client_secret:, refresh_token:)
  initialize_authenticator
  @base_url = base_url
  @default_array_class = default_array_class
  @default_object_class = default_object_class
  @connection = Connection.new(open_timeout:, read_timeout:, write_timeout:, debug_output:, proxy_url:)
  @request_builder = RequestBuilder.new
  @redirect_handler = RedirectHandler.new(connection: @connection, request_builder: @request_builder, max_redirects:)
  @response_parser = ResponseParser.new
end

Instance Attribute Details

#authenticator ⇒ Authenticator (readonly)

The authenticator for API requests

Examples:

Check if the OAuth 2.0 token has expired

client.authenticator.token_expired?

Returns:



52
53
54
 
# File 'lib/x/client.rb', line 52

def authenticator
  @authenticator
end

#base_url ⇒ String

The base URL for API requests

Examples:

Get or set the base URL

client.base_url = "https://api.twitter.com/1.1/"

Returns:

  • (String) —

    the base URL for API requests



31
32
33
 
# File 'lib/x/client.rb', line 31

def base_url
  @base_url
end

#default_array_class ⇒ Class

The default class for parsing JSON arrays

Examples:

Get or set the default array class

client.default_array_class = Set

Returns:

  • (Class) —

    the default class for parsing JSON arrays



38
39
40
 
# File 'lib/x/client.rb', line 38

def default_array_class
  @default_array_class
end

#default_object_class ⇒ Class

The default class for parsing JSON objects

Examples:

Get or set the default object class

client.default_object_class = OpenStruct

Returns:

  • (Class) —

    the default class for parsing JSON objects



45
46
47
 
# File 'lib/x/client.rb', line 45

def default_object_class
  @default_object_class
end

Instance Method Details

#delete(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class) ⇒ Hash, ...

Perform a DELETE request to the X API

Examples:

Delete a tweet

client.delete("tweets/1234567890")

Returns:

  • (Hash, Array, nil) —

    the parsed response body



143
144
145
 
# File 'lib/x/client.rb', line 143

def delete(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
  execute_request(:delete, endpoint, headers:, array_class:, object_class:)
end

#get(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class) ⇒ Hash, ...

Perform a GET request to the X API

Examples:

Get a user by username

client.get("users/by/username/sferik")

Returns:

  • (Hash, Array, nil) —

    the parsed response body



113
114
115
 
# File 'lib/x/client.rb', line 113

def get(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
  execute_request(:get, endpoint, headers:, array_class:, object_class:)
end

#post(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class) ⇒ Hash, ...

Perform a POST request to the X API

Examples:

Create a tweet

client.post("tweets", '{"text": "Hello, World!"}')

Returns:

  • (Hash, Array, nil) —

    the parsed response body



123
124
125
 
# File 'lib/x/client.rb', line 123

def post(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
  execute_request(:post, endpoint, body:, headers:, array_class:, object_class:)
end

#put(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class) ⇒ Hash, ...

Perform a PUT request to the X API

Examples:

Update a resource

client.put("some/endpoint", '{"key": "value"}')

Returns:

  • (Hash, Array, nil) —

    the parsed response body



133
134
135
 
# File 'lib/x/client.rb', line 133

def put(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
  execute_request(:put, endpoint, body:, headers:, array_class:, object_class:)
end