> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt.

# Use Ruby SDKs generated in Postman

This guide provides instructions for using Ruby SDKs generated by Postman SDK Generator. It covers how to install the SDK into your project, run example code, and best practices for using the SDK effectively in your applications.

The Postman SDK Generator creates Ruby SDKs with models, service classes for API endpoints, authentication handling, error handling, and comprehensive documentation to help you integrate with your API quickly and efficiently. Models include attribute validation, serialization support, and clear error messages to enhance development experience.

## SDK structure

Generated Ruby SDKs include the following key components:

* Main client — `lib/[sdk_name].rb` for SDK initialization and configuration.
* Service layer — Organized in `lib/[sdk_name]/services/` with individual service classes.
* Data models — Well-structured classes in `lib/[sdk_name]/models/` with validation and serialization.
* Network infrastructure — Located in `lib/[sdk_name]/http/` handling HTTP transport, configuration, and authentication.

The directory structure includes documentation files, example implementations, and gemspec configuration for Ruby ecosystem integration.

The following is an example of the typical structure of a generated Ruby SDK:

## Ruby conventions and features

Generated Ruby models follow Ruby conventions and best practices, providing a natural Ruby development experience.

### Serialization

Models serialize to API-compatible hashes using `to_h`, which applies field aliases and excludes unset attributes:

```ruby
pet = YourSdk::Models::Pet.new
pet.name = "Fluffy"
pet.status = "available"

# Serializes using the API field names
payload = pet.to_h
# {"name" => "Fluffy", "status" => "available"}
```

### Ruby naming conventions

The SDK uses Ruby naming conventions (snake\_case) for model attributes and service methods, and converts to API field names (camelCase) during serialization. This allows you to work with Ruby idioms while ensuring correct API communication.

```ruby
# Ruby style (snake_case)
user = YourSdk::Models::User.new
user.first_name = "John"
user.last_name = "Doe"
user.email_address = "john@example.com"

# Converts to API style when serialized
user.to_h
# {"firstName" => "John", "lastName" => "Doe", "emailAddress" => "john@example.com"}
```

## Example usage

Each generated SDK includes an `example/` directory with a working project demonstrating SDK usage.

The example includes the following features:

* SDK configuration and initialization
* API calls with Ruby conventions
* Error handling with custom exceptions
* Authentication setup and usage

#### Location

`example/example.rb`

#### Run the example

```bash
cd example
bundle install
bundle exec ruby example.rb
```

#### Example code structure

```ruby
require 'your_sdk'

# Initialize the SDK
sdk = YourSdk::Client.new
response = sdk.users.get_user("123")
puts response
```

## Install the Ruby SDK locally

You can install the generated SDK into your Ruby project using Bundler, RubyGems, or by adding it to your load path. Below are instructions for each method.

### Install using Bundler with local path

To install the SDK using Bundler with a local path, do the following:

1. Add the SDK to your `Gemfile`:

   ```ruby
   gem 'your-sdk', path: '../path/to/your-sdk'
   ```

2. Install dependencies:

   ```bash
   bundle install
   ```

3. Use the SDK in your code:

   ```ruby
   require 'your_sdk'

   # No auth
   client = YourSdk::Client.new

   # With bearer auth
   client = YourSdk::Client.new(token: 'YOUR_TOKEN')

   # With API key / basic auth
   client = YourSdk::Client.new(api_key: 'YOUR_KEY', username: 'user', password: 'pass')
   ```

### Install using Bundler with Git repository

To install the SDK directly from a Git repository, add the following to your `Gemfile`:

```ruby
gem 'your-sdk', git: 'https://github.com/your-org/your-sdk.git'

# Or specify a branch/tag/commit
gem 'your-sdk', git: 'https://github.com/your-org/your-sdk.git', branch: 'main'
gem 'your-sdk', git: 'https://github.com/your-org/your-sdk.git', tag: 'v1.0.0'
```

## Publish

To publish your generated Ruby SDK, see [Publish Ruby SDKs generated in Postman](/docs/sdk-generator/publish/ruby-manual/).