tiny-rest-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bbbf391dfae3b7c9331328d57465ee906873ada7424306f2338c33802a46f1d4
+  data.tar.gz: 300105bfe2e54479fb613cb977188b6eea7e80eafd56442a0f2ac9a85387fe9d
+SHA512:
+  metadata.gz: ba5ff7eb795d3b30c97c96da58f5831a504a411730ae30f171debceac4d2254226929a100b6b264521c3c450f8028e71a768f8a54edc8c63bcd064404eb2b760
+  data.tar.gz: 1ced9f35ca6a4df30e55039dae8d1927143c95de9460bcc157e3e40d43e1c421814ddd33d27b84202d3718f1b761ab736773ace5adb27cd970247fe67f203013

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-22
+
+### Added
+- First public release
+- Core client class with DSL for api_path and authorization
+- Authorization strategies:
+  - Bearer
+  - API Key with configurable location and name
+  - Basic Auth
+- Request wrapper class around Typhoeus
+- Simple success/failure response helpers
+- Full Minitest suite (classic + spec style examples)
+- Basic README documentation
+
+[Unreleased]: https://github.com/Dabrovsky/tiny_rest_client/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Dabrovsky/tiny_rest_client/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dabrovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,232 @@
+# TinyRestClient
+
+A minimal, opinionated HTTP client wrapper for Rails, built on top of Typhoeus. Perfect for quickly building clean, opinionated API clients with almost no boilerplate.
+
+### Features
+
+- Simple class-level DSL for configuration
+- Built-in support for Bearer, API Key and Basic Auth
+- Chainable-like request methods (GET, POST, PATCH, PUT, DELETE, HEAD, OPTIONS)
+
+## Why TinyRestClient?
+
+- Small, focused API clients
+- Internal services and microservices
+- Rails apps that want minimal abstraction
+- Developers who prefer convention over configuration
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Configuration](#configuration)
+- [Authorization](#authorization)
+- [Making Requests](#making-requests)
+- [Response Handling](#response-handling)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Add this line to your Gemfile:
+
+```bash
+gem "tiny-rest-client"
+```
+
+Or install it manually:
+
+```bash
+gem install tiny-rest-client
+```
+
+## Basic Usage
+
+```ruby
+class MyClient < TinyRestClient::Core
+  # define base API path (required)
+  api_path "https://api.example.com/v1"
+
+  # set an authorization strategy (optional)
+  authorization :bearer, token: "your_token"
+
+  # pass single header (optional)
+  header "Accept", "application/json"
+
+  # pass bunch of headers (optional)
+  headers "User-Agent": "MyTest/1.0", "Accept": "application/json"
+
+  # define actions
+  def fetch_todos(**)
+    get("/todos", **)
+  end
+
+  def fetch_todo(id)
+    get("/todos/#{id}")
+  end
+
+  def create_todo(**)
+    post("/todos", **)
+  end
+
+  def update_todo(id, **)
+    patch("/todos/#{id}", **)
+  end
+
+  def destroy_todo(id)
+    delete("/todos/#{id}")
+  end
+end
+
+client = MyClient.new
+
+client.fetch_todos(page: 1, per_page: 20)
+client.fetch_todo(1)
+client.create_todo(name: "Custom")
+client.update_todo(status: "finished")
+client.destroy_todo(1)
+```
+
+## Configuration
+
+You can configure client setup at the class level:
+
+```ruby
+class MyClient < TinyRestClient::Core
+  api_path "https://api.example.com/v1"
+  authorization :bearer, token: "your_token"
+  headers "Accept": "application/json", "User-Agent", "MyApp/1.0"
+end
+
+client = MyClient.new
+```
+
+Or per instance:
+
+```ruby
+class MyClient < TinyRestClient::Core; end
+
+client = MyClient.new(
+  api_path: "https://api.example.com/v1",
+  auth: { bearer: { token: "your_token" } },
+  headers: { "User-Agent": "MyApp/1.0" }
+)
+```
+
+## Authorization
+
+The library ships with a small set of built‑in strategies:
+
+* Bearer Token
+* API Keys
+* Basic Auth
+
+You can configure authentication either at the class level using the
+`authorization` helper or at runtime via the `auth` key when initializing a
+client (see "Configuration" above).
+
+#### Options Overview
+
+```ruby
+# Bearer
+:bearer, token: String                             # Authorization: Bearer <token>
+
+# API key
+:api_key, token: String                            # X-API-Key: <token>
+:api_key, token: String, name: String              # <Custom>: <token>
+:api_key, token: String, in: :param                # ?api_key=<token>
+:api_key, token: String, in: :param, name: String  # ?<custom>=<token>
+
+# Basic
+:basic_auth, user: String, password: String        # Authorization: Basic <base64(user:password)>
+```
+
+### Bearer Token
+
+```ruby
+class MyClient < TinyRestClient::Core
+  authorization :bearer, token: "your_token"
+end
+
+# per-instance
+MyClient.new(auth: { bearer: { token: "your_token" } })
+```
+
+### API Key
+
+```ruby
+class MyClient < TinyRestClient::Core
+  authorization :api_key, token: "your_token"
+end
+
+# per-instance
+MyClient.new(auth: { api_key: { token: "your_token" } })
+```
+
+### Basic Auth
+
+```ruby
+class MyClient < TinyRestClient::Core
+  authorization :basic_auth, user: "name", password: "secret"
+end
+
+# per-instance
+MyClient.new(auth: { basic_auth: { user: "name", password: "secret" } })
+```
+
+## Making Requests
+
+The standard HTTP methods are available directly on every client instance automatically include any headers and/or authorization configuration you defined.
+
+```ruby
+get("/users", page: 1, per_page: 10)            # GET request with query parameters
+post("/users", name: "John", surname: "Doe")    # POST request with body
+put("/users/1")                                 # PUT request
+patch("/users/1")                               # PATCH request
+delete("/users/1")                              # DELETE request
+head("/users/1")                                # HEAD request
+options("/users")                               # OPTIONS request
+```
+
+## Response Handling
+
+Every request returns an instance of [TinyRestClient::Response](https://github.com/Dabrovsky/tiny-rest-client/blob/main/lib/tiny_rest_client/response.rb). A thin
+wrapper around the raw Typhoeus response that provides a few convenient
+helpers:
+
+| Method | Description |
+|--------|-------------|
+| success? | Helper that represent successful response. |
+| failure? | The opposite. |
+| code | HTTP status code (e.g. `200`, `404`). |
+| status | Return code symbol (e.g. `:ok`, `:couldnt_connect`). |
+| headers | Hash of response headers (keys are not normalized). |
+| body | Auto-parsed JSON (symbolized keys). If parsing fails, returns the original raw string. |
+
+```ruby
+response.success?    # true if code 200–299
+response.failure?    # opposite
+response.code        # HTTP status code (Integer)
+response.status      # Typhoeus return_code symbol
+response.body        # auto-parsed JSON hash or raw string
+response.headers     # hash of response headers
+```
+
+## Error Behavior
+
+TinyRestClient does not raise exceptions for HTTP status codes.
+
+Network-level errors (timeouts, connection failures, etc.) are reflected in:
+
+* response.status
+* response.success? / response.failure?
+
+This makes error handling explicit and predictable.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://github.com/Dabrovsky/tiny-rest-client/blob/main/LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tiny_rest_client"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tiny_rest_client/request.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Request
+  attr_reader :method, :api_path, :headers, :body, :params, :endpoint, :rest
+
+  def initialize(method, api_path, endpoint: "", headers: nil, auth_config: nil, body: nil, params: nil)
+    @method = method || :get
+    @api_path = api_path || raise(ArgumentError, "Define api_path base URL")
+    @endpoint = endpoint
+    @headers = headers
+    @body = body
+    @params = params
+    @rest = {}
+
+    configure_auth(auth_config)
+  end
+
+  def run
+    Response.new(
+      code: response.code,
+      status: response.return_code,
+      body: response.body,
+      headers: response.headers
+    )
+  rescue Typhoeus::Errors::TyphoeusError => e
+    Response.new(
+      code: 0,
+      status: :internal_error,
+      body: e.message.capitalize,
+      headers: {}
+    )
+  end
+
+  private
+
+  def configure_auth(auth_config)
+    return unless auth_config
+
+    type, config = auth_config.first
+    strategy = Strategies::Auth::Registry.fetch(type)
+    strategy.new(**config[:credentials]).execute(self)
+  end
+
+  def request
+    @request = Typhoeus::Request.new(
+      [api_path, endpoint].join, method:, body:, params:, headers:, **rest
+    )
+  end
+
+  def response
+    @response ||= request.run
+  end
+end

data/lib/tiny_rest_client/response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# The Response class represents a response object that
+# can be used to represent success or failure outcomes
+class Response
+  attr_reader :code, :status, :body, :headers
+
+  def initialize(code: nil, status: nil, body: nil, headers: nil)
+    @code = code
+    @status = status
+    @headers = headers
+    @body = parse_body(body)
+  end
+
+  def success?
+    code.to_i.between?(200, 299)
+  end
+
+  def failure?
+    !success?
+  end
+
+  def parse_body(raw_body)
+    return raw_body unless raw_body.is_a?(String)
+
+    begin
+      JSON.parse(raw_body, symbolize_names: true)
+    rescue JSON::ParserError
+      raw_body
+    end
+  end
+end

data/lib/tiny_rest_client/strategies/auth/api_key.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Strategies
+  module Auth
+    class ApiKey < Base
+      attr_reader :token, :location, :name
+
+      def initialize(credentials = {})
+        @token = require!(credentials[:token], :token)
+        @location = credentials.fetch(:in, :header).to_sym
+        @name = credentials.fetch(:name) do
+          location == :header ? "X-API-Key" : "api_key"
+        end
+      end
+
+      def execute(request)
+        case location
+        when :header
+          request.headers[name] = token
+        when :query, :param
+          request.params[name] = token
+        else
+          raise ArgumentError, "Invalid key: #{location}. Allowed keys: :header or :query."
+        end
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/strategies/auth/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Strategies
+  module Auth
+    class Base
+      def execute
+        raise NotImplementedError
+      end
+
+      private
+
+      def require!(value, name)
+        value || raise(ArgumentError, "Missing #{name} parameter")
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/strategies/auth/basic_auth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Strategies
+  module Auth
+    class BasicAuth < Base
+      attr_reader :user, :pass
+
+      def initialize(credentials = {})
+        @user = require!(credentials[:user], :user)
+        @pass = require!(credentials[:password], :password)
+      end
+
+      def execute(request)
+        request.rest[:userpwd] = "#{user}:#{pass}"
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/strategies/auth/bearer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Strategies
+  module Auth
+    class Bearer < Base
+      attr_reader :token
+
+      def initialize(credentials = {})
+        @token = require!(credentials[:token], :token)
+      end
+
+      def execute(request)
+        request.headers["Authorization"] = "Bearer #{token}"
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/strategies/auth/registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Strategies
+  module Auth
+    module Registry
+      STRATEGIES = {
+        bearer: Bearer,
+        api_key: ApiKey,
+        basic_auth: BasicAuth
+      }.freeze
+
+      module_function
+
+      def fetch(type)
+        STRATEGIES.fetch(type) do
+          raise ArgumentError, "Unsupported auth type: #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TinyRestClient
+  VERSION = "0.1.0"
+end

data/lib/tiny_rest_client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "typhoeus"
+require "json"
+
+require "tiny_rest_client/strategies/auth/base"
+require "tiny_rest_client/strategies/auth/basic_auth"
+require "tiny_rest_client/strategies/auth/bearer"
+require "tiny_rest_client/strategies/auth/api_key"
+require "tiny_rest_client/strategies/auth/registry"
+require "tiny_rest_client/request"
+require "tiny_rest_client/response"
+require "tiny_rest_client/version"
+
+module TinyRestClient
+  class Core
+    class << self
+      def api_path(value = nil)
+        @api_path ||= value
+      end
+
+      def authorization(type = nil, **credentials)
+        if type
+          @auth_config = {
+            type.to_sym => { credentials: }
+          }
+        else
+          @auth_config
+        end
+      end
+
+      def header(name, value)
+        @headers ||= {}
+        @headers[name] = value
+        @headers
+      end
+
+      def headers(hash = nil)
+        if hash
+          @headers = (@headers || {}).merge(hash.transform_keys(&:to_s))
+        else
+          @headers || {}
+        end
+      end
+    end
+
+    attr_reader :api_path, :auth_config, :headers
+
+    def initialize(api_path: nil, auth: nil, headers: {})
+      @api_path = api_path || self.class.api_path || raise(ArgumentError, "Undefined api_path base URL")
+      @auth_config = auth || self.class.authorization
+      @headers = merge_headers(headers)
+    end
+
+    def head(endpoint, params = {})
+      Request.new(:head, api_path, endpoint:, params:, **common_params).run
+    end
+
+    def get(endpoint, params = {})
+      Request.new(:get, api_path, endpoint:, params:, **common_params).run
+    end
+
+    def post(endpoint, body = {})
+      Request.new(:post, api_path, endpoint:, body:, **common_params).run
+    end
+
+    def patch(endpoint, body = {})
+      Request.new(:patch, api_path, endpoint:, body:, **common_params).run
+    end
+
+    def put(endpoint, body = {})
+      Request.new(:put, api_path, endpoint:, body:, **common_params).run
+    end
+
+    def delete(endpoint, params = {})
+      Request.new(:delete, api_path, endpoint:, params:, **common_params).run
+    end
+
+    def options(endpoint, params = {})
+      Request.new(:options, api_path, endpoint:, params:, **common_params).run
+    end
+
+    private
+
+    def merge_headers(instance_headers)
+      (self.class.headers || {}).merge(instance_headers || {}).transform_keys(&:to_s)
+    end
+
+    def common_params
+      { headers:, auth_config: }
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: tiny-rest-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dabrovski
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: A lightweight, Ruby-friendly HTTP client that makes HTTP requests simple
+  and easy to use.
+email:
+- wojciech.dabrovski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/tiny_rest_client.rb
+- lib/tiny_rest_client/request.rb
+- lib/tiny_rest_client/response.rb
+- lib/tiny_rest_client/strategies/auth/api_key.rb
+- lib/tiny_rest_client/strategies/auth/base.rb
+- lib/tiny_rest_client/strategies/auth/basic_auth.rb
+- lib/tiny_rest_client/strategies/auth/bearer.rb
+- lib/tiny_rest_client/strategies/auth/registry.rb
+- lib/tiny_rest_client/version.rb
+homepage: https://github.com/Dabrovsky/tiny-rest-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Dabrovsky/tiny-rest-client
+  source_code_uri: https://github.com/Dabrovsky/tiny-rest-client
+  changelog_uri: https://github.com/Dabrovsky/tiny-rest-client/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.5
+signing_key: 
+specification_version: 4
+summary: A minimal REST client gem for Rails
+test_files: []