***

title: Use Ruby SDKs generated in Postman
max-toc-depth: 2
topictype: reference
---------------------

For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. For full content including API reference and SDK examples, see https://learning.postman.com/llms-full.txt.

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:

<Folder name="your-sdk" defaultOpen>
  <Files>
    <File name="README.md" comment="Main documentation" />

    <File name="Gemfile" comment="Gem dependencies for development" />

    <File name="your-sdk.gemspec" comment="Gem specification" />
  </Files>

  <Folder name="lib">
    <Files>
      <File name="your_sdk.rb" comment="Main SDK entry point" />
    </Files>

    <Folder name="your_sdk">
      <Files>
        <File name="client.rb" comment="Main SDK client class" />

        <File name="environment.rb" comment="Environment handling" />

        <File name="error.rb" comment="Error and APIError classes" />

        <File name="version.rb" comment="Version constant" />
      </Files>

      <Folder name="services">
        <Files>
          <File name="[resource_name].rb" comment="Resource-specific service class" />

          <File name="[service_name].rb" comment="Individual service classes" />
        </Files>
      </Folder>

      <Folder name="models">
        <Files>
          <File name="[model_name].rb" comment="Data model classes" />
        </Files>
      </Folder>

      <Folder name="http">
        <Files>
          <File name="auth.rb" comment="Authentication handling" />

          <File name="connection.rb" comment="HTTP connection management" />

          <File name="response.rb" comment="Response processing" />
        </Files>
      </Folder>
    </Folder>
  </Folder>

  <Folder name="example">
    <Files>
      <File name="example.rb" comment="Basic usage example" />
    </Files>
  </Folder>

  <Folder name="documentation">
    <Folder name="services">
      <File name="[service_name].md" comment="Service documentation" />
    </Folder>

    <Folder name="models">
      <File name="[model_name].md" comment="Model documentation" />
    </Folder>

    <Folder name="snippets">
      <File name="snippets.json" comment="Code snippets" />
    </Folder>
  </Folder>
</Folder>

## 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

<Tabs>
  <Tab title="Location">
    `example/example.rb`
  </Tab>

  <Tab title="Run the example">
    ```bash
    cd example
    bundle install
    bundle exec ruby example.rb
    ```
  </Tab>

  <Tab title="Example code structure">
    ```ruby
    require 'your_sdk'

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

## 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 RubyGems

To share your generated Ruby SDK with the community, you can publish it to RubyGems. This allows other developers to easily install it using `gem install`. Follow the steps below to publish your SDK to RubyGems.

### Publish your Ruby SDK to RubyGems

To publish your SDK to RubyGems, do the following:

1. If you haven't done so, create a RubyGems account:

   * Register at [rubygems.org](https://rubygems.org/sign_up).
   * Set up your API credentials:

   ```bash
   gem push --help  # This will prompt for credentials on first use
   ```

2. Prepare your gem for publishing:

   ```bash
   # Check code style
   bundle exec rubocop

   # Build the gem
   gem build your-sdk.gemspec
   ```

   This creates `your-sdk-1.0.0.gem` in the current directory.

3. Validate the gem:

   ```bash
   gem specification your-sdk-1.0.0.gem
   ```

4. Publish to RubyGems:

   ```bash
   gem push your-sdk-1.0.0.gem
   ```

5. Verify publication:

   ```bash
   gem install your-sdk
   # Or visit: https://rubygems.org/gems/your-sdk
   ```

### Publish updates

1. Update the version in `lib/your_sdk/version.rb`:

   ```ruby
   module YourSdk
     VERSION = "1.0.1"
   end
   ```

2. Update `CHANGELOG.md` with changes.

3. Build and publish:

   ```bash
   gem build your-sdk.gemspec
   gem push your-sdk-1.0.1.gem
   ```

### Best practices for publishing Ruby SDKs

Use the following best practices when publishing your Ruby SDK to RubyGems:

* Use semantic versioning (`MAJOR.MINOR.PATCH`).
* Maintain a `CHANGELOG.md` documenting changes.
* Use YARD documentation comments for API documentation.
* Follow Ruby style guidelines (use RuboCop).
* Pin major versions of dependencies in your gemspec.
* Include metadata URLs in your gemspec for better discoverability.
* Test your gem installation in a clean environment before publishing.