---
name: ruby-getting-started
description: APIMatic-generated Ruby SDK (APIMATIC v3.0, built on apimatic_core + apimatic_faraday_client_adapter) reference and grounding layer — gem id and top-level module, the single Client class built with keyword args (XxxCredentials objects + environment: + http kwargs), Environment and Server constants inside the Configuration class, APIException base, Faraday-backed HTTP, ApiResponse return, required Ruby version, and how to navigate the generated source. Entry point into the companion ruby-* skills (ruby-client-initialization, ruby-authentication, ruby-calling-endpoints, ruby-models, ruby-error-handling, ruby-configuration-resilience, ruby-testing) — gates loading each at its integration step, since the source shows signatures but not the usage gotchas these skills carry.
---

# Getting started with an APIMatic-generated Ruby SDK

> Controller classes are `{Resource}Api` and are reached as memoized readers on the client —
> `client.{resource}`. The `Api` suffix is a generator setting, so **confirm it** from the class
> names under `lib/{pkg}/apis/`.

This is the **SDK-specific** reference and grounding layer, and the entry into the companion
`ruby-*` skills. These SDKs are produced by **APIMATIC v3.0** (every generated file carries a
`This file was automatically generated by APIMATIC v3.0` header) and depend on three runtime gems:
`apimatic_core_interfaces`, `apimatic_core`, and `apimatic_faraday_client_adapter`. For the general
patterns that apply to *any* such SDK (client setup, auth, calling endpoints, models, error handling,
retries, testing), see the companion API-agnostic skills: `ruby-client-initialization`,
`ruby-authentication`, `ruby-calling-endpoints`, `ruby-models`, `ruby-error-handling`,
`ruby-configuration-resilience`, `ruby-testing`.

**The source and these companion skills are complementary — load both.** The generated source is
authoritative for the SDK's *surface* (constructor keyword arguments, controller method names,
credentials class names, `Environment` constants, which error type an operation raises); the companion
skills are the *usage layer* on top — the right way to call each piece and the gotchas a signature
can't show. Reading the source doesn't remove the need to load the skill for that step, so at each step
below load the companion *and* confirm names against the source.

> **Before writing any integration code, clone the SDK source** (one command, in the *SDK source*
> section below) and read it to confirm every keyword argument, class name, constant, and error type as
> you go. Do **not** copy the SDK source into your project, and do **not** fetch GitHub files ad hoc —
> clone once, then grep the local copy. It's a throwaway reference: delete it when the integration is
> done.

## SDK identity

| | |
| --- | --- |
| API | `X API v2` |
| Generator | APIMATIC v3.0 (`automatically generated by APIMATIC v3.0` header on every file) |
| Runtime dependencies | `apimatic_core_interfaces`, `apimatic_core`, `apimatic_faraday_client_adapter` — pulled transitively via the gem |
| Gem id | the `name` in the `.gemspec` (e.g. `multi_auth_sample`, `apimatic_calculator_by_client`) — per-API |
| Top-level module | CamelCase of the gem id (e.g. `MultiAuthSample`, `ApimaticCalculatorByClient`) |
| Install | `gem 'x_api_v2', git: 'https://github.com/context-plugins/x-api-v2-ruby-sdk', branch: 'main'` in a Gemfile |
| Client class | `XAPIV2::Client` — one class; built with `Client.new(keyword_args...)` or `Client.from_env` |
| Configuration class | `XAPIV2::Configuration` — extends `CoreLibrary::HttpClientConfiguration`; holds `Environment` and `Server` inner classes |
| Auth pattern | typed `{Scheme}Credentials` objects passed as keyword args to `Client.new` — see **ruby-authentication** |
| Environment constants | frozen string constants nested inside `Configuration`. Only the first is named meaningfully (`Environment::PRODUCTION`); further servers are positional placeholders (`Environment::ENVIRONMENT2`, …), and there is **no** `TESTING` constant. A single-server API gets `PRODUCTION` alone |
| Controllers | accessed via snake_case methods on the client (e.g. `client.simple_calculator`) — lazy-initialized with `||=` |
| Return type | every operation returns an `ApiResponse` object with `.status_code`, `.headers`, `.data`, `.raw_body`, `.request` |
| Base exception | `XAPIV2::APIException` (extends `CoreLibrary::ApiException`) |
| HTTP layer | Faraday via `apimatic_faraday_client_adapter` (`CoreLibrary::FaradayClient`); inject a custom `Faraday::Connection` via `connection:` or swap the adapter via `adapter:` |
| Ruby version | `>= 2.6` (from `.gemspec` `required_ruby_version`) |

The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (gem id,
`Client`/`Configuration`, the auth *pattern*, the environments), while the actual integration code
comes from the companion skills. Load each one as you reach its step (see **Integration workflow**
below) and confirm its types against the cloned source.

## Package layout under lib/

APIMatic Ruby SDKs place everything under `lib/x_api_v2/`:

- `lib/x_api_v2.rb` — top-level require that loads `apimatic_core`, `apimatic_faraday_client_adapter`, then all internal files.
- `lib/x_api_v2/client.rb` — the `Client` class: `initialize` with all keyword args (http options + credentials), controller accessor methods (e.g. `def simple_calculator`), OAuth manager accessors (e.g. `def o_auth_ccg`), and `self.from_env`.
- `lib/x_api_v2/configuration.rb` — `Configuration` class (extends `CoreLibrary::HttpClientConfiguration`) with `Environment` and `Server` inner constant classes, the `ENVIRONMENTS` hash mapping environment+server to base URIs, `get_base_uri`, and `clone_with`.
- `lib/x_api_v2/controllers/` — one `{Resource}Api` per API resource group, each extending `BaseController`. **This is where operation method signatures and required vs. optional params live.**
- `lib/x_api_v2/models/` — model classes (extend `BaseModel`) and enum modules with frozen string constants.
- `lib/x_api_v2/exceptions/` — `api_exception.rb` (`APIException`) plus any typed error subclasses.
- `lib/x_api_v2/http/auth/` — one file per auth scheme (`basic_auth.rb`, `o_auth_ccg.rb`, etc.), each containing both the handler class (extends `CoreLibrary::HeaderAuth` or `CoreLibrary::QueryAuth`) and the `{Scheme}Credentials` data class with `initialize`, `from_env`, and `clone_with`.
- `lib/x_api_v2/utilities/` — `file_wrapper.rb`, `date_time_helper.rb`.
- `doc/` — human-readable generated reference: `doc/client.md`, `doc/auth/*.md`, `doc/controllers/*.md`, `doc/models/*.md`, `doc/api-response.md`, `doc/environment-based-client-initialization.md`. **Grep `doc/` first** — fastest path to a method name, its parameters, and a usage snippet.

## Install

```ruby
# In your Gemfile:
gem 'x_api_v2', git: 'https://github.com/context-plugins/x-api-v2-ruby-sdk', branch: 'main'
```

Then run `bundle install`.

Then require the gem at the top of your integration:

```ruby
require 'x_api_v2'
include XAPIV2   # optional — lets you write Client.new instead of XAPIV2::Client.new
```

> `bundle install` pulls `apimatic_core_interfaces`, `apimatic_core`, and
> `apimatic_faraday_client_adapter` transitively.

## SDK source — clone it first; don't fetch files ad hoc

You will constantly need to confirm real keyword argument names, constructor signatures, model class
names, enum constants, and error types, and the **only reliable way** is to read the SDK source. Clone
it once, up front — before writing integration code — into your **system temp directory** (outside your
project), then read and grep the local copy. It is a read-only, throwaway reference:

```bash
# Linux / macOS:
git clone --depth 1 --branch main https://github.com/context-plugins/x-api-v2-ruby-sdk /tmp/x-api-v2-ruby-src
```

```powershell
# Windows (PowerShell):
git clone --depth 1 --branch main https://github.com/context-plugins/x-api-v2-ruby-sdk "$env:TEMP\x-api-v2-ruby-src"
```

Then confirm the SDK shape **only** from that local clone:

- **Don't fetch GitHub files one at a time** — `…/blob/…` pages return HTML and guessed paths fail.
  Clone once and read locally. Only if `git` is unavailable, fetch a **raw** URL of the form
  `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/…` (never a `…/blob/…` page).

Layout — grep the clone here first:

- `.gemspec` — the gem `name`, `required_ruby_version`, and the three `apimatic_*` runtime dependencies.
- `lib/x_api_v2/client.rb` — the full `initialize` keyword list (http kwargs + credentials kwargs), controller accessors, OAuth manager accessors, and `from_env`.
- `lib/x_api_v2/configuration.rb` — `Environment` and `Server` constants, the `ENVIRONMENTS` hash (maps environment+server strings to base URI templates), and `clone_with`.
- `lib/x_api_v2/http/auth/*.rb` — credentials classes for every scheme this API uses, including their `initialize` keyword args and `from_env` env-var names.
- `lib/x_api_v2/controllers/*.rb` — operation method signatures; **this is where required vs. optional params live**.
- `lib/x_api_v2/models/` — model classes and enum modules; **this is where field names and enum values live**.
- `lib/x_api_v2/exceptions/` — `APIException` and typed subclasses.
- `README.md` and `doc/` — generated human-readable index: `doc/client.md`, `doc/auth/*.md`,
  `doc/controllers/*.md`, `doc/models/*.md`, `doc/api-response.md`, `doc/environment-based-client-initialization.md`.
  **Grep `doc/` first** — it is the fastest way to find an operation, its parameters, and a usage snippet.

Clean up when done:

```bash
rm -rf /tmp/x-api-v2-ruby-src                               # Linux / macOS
```
```powershell
Remove-Item -Recurse -Force "$env:TEMP\x-api-v2-ruby-src"   # Windows
```

## Integration workflow — load the companion skill at each step

Before you write the code for each step, load the named companion skill — even if you've already read
the relevant source. Each step calls out the trap the signature hides (in *parens*).

1. **Client construction** — load **ruby-client-initialization** before you call `Client.new(...)` or
   `Client.from_env`. (*The signature won't tell you:* every param is a keyword arg — none are
   positional; you can pass a pre-built `Configuration` via `config:` to skip per-param kwargs; the
   client should be constructed once and reused — it lazily memoizes controllers.)
2. **Authentication** — load **ruby-authentication** before you set credentials. (*The signature won't
   tell you:* each scheme is a **typed `{Scheme}Credentials` data class** — e.g.
   `OAuthCCGCredentials.new(o_auth_client_id:, o_auth_client_secret:)` — not a bare string; credentials
   classes also expose `from_env` and `clone_with`; to update credentials you must call
   `config.clone_with(...)` and rebuild the client.)
3. **Calling an endpoint** — load **ruby-calling-endpoints** before the first
   `client.{resource}.{method}(...)` call. (*The signature won't tell you:* controllers are accessed
   via snake_case methods on the client — not instantiated directly; some methods take positional
   required args while others take an `options` hash — read the signature; the return is always an
   `ApiResponse` object, not the bare data; read `.data` for the deserialized result.)
4. **Models** — load **ruby-models** the moment a request/response field isn't a plain string or
   number. (*The signature won't tell you:* models extend `BaseModel` and are constructed with keyword
   args; enums are frozen string constants in a module — use the constant, not a raw string; union/anyOf
   types use `ApiHelper` helpers.)
5. **Error handling** — load **ruby-error-handling** before your first `rescue`. (*The signature won't
   tell you:* a non-2xx response raises `APIException` — or a typed subclass in `exceptions/` when the
   API documents that error; the exception carries `#response_code` and `#response`; typed errors are
   only generated when the API spec documents them, so check `exceptions/` in the source.)
6. **Configuration and resilience** — load **ruby-configuration-resilience** when you tune retries,
   timeouts, or the Faraday connection. (*The signature won't tell you:* retries are **disabled by
   default** (`max_retries: 0`) and only `GET`/`PUT` are retried even when enabled; inject a custom
   `Faraday::Connection` via `connection:` for proxy, TLS, or test adapters.)
7. **Testing** — load **ruby-testing** before you stub the SDK. (*The signature won't tell you:* the
   test seam is a `Faraday::Adapter::Test` stubs block injected via `connection:`, or an
   `HttpCallBack` for pre/post hooks; the generated test suite uses `minitest` with `minitest-proveit`.)