Chapter 21: API Client#

1. Talking to Other Services#

Your app does not live in isolation. It calls payment gateways, weather APIs, shipping providers, CRM platforms, and internal microservices. Each call needs a base URL, auth headers, timeout handling, and response parsing.

Tina4's API client handles that boilerplate. One configured instance gives you clean get, post, put, and delete calls with a consistent response format and no external gem required.

2. Creating a Client#

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

All requests use this base URL. Paths are appended to it.

With Default Headers#

client = Tina4::Api.new("https://api.example.com", {  "Content-Type" => "application/json",  "Accept"       => "application/json"})

Headers set here are sent with every request.

3. GET Requests#

result = client.get("/products")​if result.success?  puts result.body.inspectelse  puts "Error #{result.status}: #{result.body}"end

With Query Parameters#

result = client.get("/products", params: { category: "keyboards", in_stock: true })# Requests: GET /products?category=keyboards&in_stock=true

Response Object#

Every call returns a response object with:

• result.success? -- true if HTTP status is 2xx
• result.status -- integer HTTP status code
• result.body -- parsed JSON (Hash or Array) or raw string
• result.headers -- response headers Hash

4. POST Requests#

result = client.post("/orders", body: {  email: "alice@example.com",  items: [{ sku: "KB-100", qty: 1 }],  total: 79.99})​if result.success?  order_id = result.body["id"]  puts "Order created: #{order_id}"else  puts "Failed: #{result.body["message"]}"end

The body is serialized to JSON automatically. The Content-Type: application/json header is set if not already present.

5. PUT Requests#

result = client.put("/orders/101", body: {  status: "shipped",  tracking_number: "1Z999AA10123456784"})​puts result.success? ? "Updated" : "Failed: #{result.status}"

6. DELETE Requests#

result = client.delete("/orders/101")​if result.success?  puts "Order deleted"else  puts "Delete failed: #{result.status}"end

7. Authentication Headers#

Bearer Token#

client = Tina4::Api.new("https://api.example.com", {  "Authorization" => "Bearer #{ENV['API_TOKEN']}",  "Content-Type"  => "application/json"})

API Key Header#

client = Tina4::Api.new("https://api.stripe.com", {  "Authorization" => "Bearer #{ENV['STRIPE_SECRET_KEY']}",  "Stripe-Version" => "2024-11-20"})

Basic Auth#

require "base64"​credentials = Base64.strict_encode64("#{ENV['API_USER']}:#{ENV['API_PASS']}")​client = Tina4::Api.new("https://api.example.com", {  "Authorization" => "Basic #{credentials}"})

Per-Request Header Override#

Pass headers directly on a single call to override or extend the defaults:

result = client.get("/admin/users", headers: {  "X-Admin-Token" => "secret-admin-key"})

8. Timeouts#

client = Tina4::Api.new("https://api.slow.com", {}, timeout: 10)# Raises Tina4::ApiTimeout after 10 seconds with no response

Default timeout is 30 seconds.

9. Using the Client in Route Handlers#

# @noauthTina4::Router.get("/api/weather") do |request, response|  city = request.params["city"] || "London"​  weather_client = Tina4::Api.new("https://api.openweathermap.org", {    "Accept" => "application/json"  })​  result = weather_client.get("/data/2.5/weather", params: {    q:     city,    appid: ENV["OPENWEATHER_API_KEY"],    units: "metric"  })​  if result.success?    data = result.body    response.json({      city:        data["name"],      temperature: data.dig("main", "temp"),      description: data.dig("weather", 0, "description")    })  else    response.json({ error: "Weather data unavailable" }, 502)  endend

curl "http://localhost:7147/api/weather?city=Paris"

{  "city": "Paris",  "temperature": 14.3,  "description": "partly cloudy"}

10. Shared Client Instances#

Define shared clients once and reuse them across routes.

# src/clients/stripe.rbSTRIPE = Tina4::Api.new("https://api.stripe.com", {  "Authorization"  => "Bearer #{ENV['STRIPE_SECRET_KEY']}",  "Content-Type"   => "application/json",  "Stripe-Version" => "2024-11-20"})​# src/routes/payments.rbTina4::Router.post("/api/checkout") do |request, response|  body = request.body​  result = STRIPE.post("/v1/payment_intents", body: {    amount:   (body["total"].to_f * 100).to_i,    currency: "usd",    metadata: { order_id: body["order_id"] }  })​  if result.success?    response.json({ client_secret: result.body["client_secret"] }, 201)  else    Tina4::Log.error("Stripe error", status: result.status, error: result.body["error"]["message"])    response.json({ error: "Payment failed" }, 502)  endend

11. Error Handling#

begin  result = client.get("/products")​  case result.status  when 200..299    process(result.body)  when 401    raise "Unauthorized -- check API credentials"  when 429    Tina4::Log.warning("Rate limited", retry_after: result.headers["Retry-After"])  when 500..599    raise "Remote server error: #{result.status}"  end​rescue Tina4::ApiTimeout => e  Tina4::Log.error("API request timed out", error: e.message)rescue => e  Tina4::Log.error("API request failed", error: e.message)end

12. Gotchas#

1. Never hard-code credentials#

Always read tokens from environment variables. Hard-coded credentials end up in version control.

2. Check success? before reading body#

result.body on a 4xx or 5xx response contains the error payload, not the data you expect.

3. Timeout is per-request#

A shared client instance with timeout: 5 applies that timeout to every request. Override per call if some endpoints are slower than others.

4. Base URL trailing slash#

Tina4::Api.new("https://api.example.com/") with a trailing slash and client.get("/products") with a leading slash double up to https://api.example.com//products. Use a base URL without a trailing slash.

13. Uploading Files (New in 3.13.69)#

upload posts a multipart/form-data body: a file plus optional text fields. Supply the file two ways, so your code never stages a temp file first.

api = Tina4::API.new("https://api.example.com", bearer_token: ENV["API_TOKEN"])​# A file on disk. filename: defaults to the basename.result = api.upload("/avatars", file_path: "/tmp/me.png")​# In-memory bytes. Pass a filename so the server sees a real name.raw = build_thumbnail            # String of bytesresult = api.upload("/avatars",  file_bytes: raw,  filename: "me.png",  extra_fields: { "user_id" => "42" })   # extra text parts

The full signature:

api.upload(path, file_path: nil, field_name: "file",           extra_fields: {}, headers: {},           file_bytes: nil, filename: nil) -> APIResponse

field_name: is the form field the file rides under (default "file"). extra_fields: become additional text parts. headers: merge extra per-call headers onto the request. The part's Content-Type is guessed from the filename, falling back to application/octet-stream.

upload returns an APIResponse. A missing file, or no source at all, returns a clean error response (status is 0, error is set) and never raises. Nothing is sent over the wire.

Breaking change in 3.13.69. file_path was the second positional argument; it is now a keyword (file_path:). Update call sites from api.upload("/path", "/tmp/me.png") to api.upload("/path", file_path: "/tmp/me.png"). This reconciles Ruby with the upload signature the other three frameworks already use.

14. Streaming Downloads (New in 3.13.69)#

download streams a GET body straight to disk, 64KB at a time. A large export never buffers whole in memory.

result = api.download("/reports/2026.csv", dest_path: "/tmp/2026.csv")​puts "saved to #{result.path}" if result.error.nil?   # /tmp/2026.csv

The signature is download(path, dest_path: nil, params: {}). It returns an APIResponse whose body is nil (the body went to disk) and whose path reader holds the destination. On any error (no dest, an HTTP error status, or a transport failure) path is nil and no file is written. status is 0 on a transport failure.

15. Testing Your Code: the transport Seam (New in 3.13.69)#

The constructor accepts a transport: object that fully replaces the Net::HTTP call. Point it at your own callable and the code that calls an API runs in a unit test with no live server.

fake = ->(method, url, headers, body, timeout) {  { http_code: 200, body: '{"ok":true}', headers: {}, error: nil }}​api = Tina4::API.new("https://api.example.com", transport: fake)result = api.get("/health")     # returns the canned response, opens no socket

The object must respond to call(method, url, headers, body, timeout) and return a Hash shaped like { http_code:, body:, headers:, error: } (string or symbol keys both work).

This seam is for your tests, not Tina4's. The framework's own suite never injects a fake transport: it follows the no-mock rule and drives the real network against a real local server. Reach for transport: to test the code that calls an API, never to stand in for API itself.

16. The Cookie Jar (New in 3.13.69)#

Pass cookies: true and the client keeps a per-instance, in-memory cookie jar. It reads Set-Cookie on each response and replays the accumulated Cookie header on the next request, so a session carries across a login and the calls that follow.

api = Tina4::API.new("https://api.example.com", cookies: true)​api.post("/login", body: { user: "alice", pass: "secret" })   # server sets a session cookieapi.get("/account")                                            # the cookie is sent automatically

The jar is off by default. It keeps only the leading name=value of each cookie, it is never persisted, and it is scoped to the instance.

17. Redirects and Cross-Origin Safety (New in 3.13.69)#

Net::HTTP does not follow redirects on its own. The client now does, bounded to ten hops. A 301, 302, or 303 on a non-GET/HEAD method becomes a GET with the body dropped; 307 and 308 keep the method and body.

On a redirect that crosses to a different origin (a different scheme, host, or port), the client strips the Authorization header and the cookie-jar Cookie header before following. That strip is a security boundary: without it, a call to https://api.example.com/login that redirected to https://evil.example/ would hand your bearer token and session cookie to a host you never authenticated against. Same-origin redirects keep both headers.

You get this on every verb and on download, with nothing to switch on.