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:

1
pet = YourSdk::Models::Pet.new
2
pet.name = "Fluffy"
3
pet.status = "available"
4
5
# Serializes using the API field names
6
payload = pet.to_h
7
# {"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.

1
# Ruby style (snake_case)
2
user = YourSdk::Models::User.new
3
user.first_name = "John"
4
user.last_name = "Doe"
5
user.email_address = "john@example.com"
6
7
# Converts to API style when serialized
8
user.to_h
9
# {"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

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:

   1
   gem 'your-sdk', path: '../path/to/your-sdk'

2. Install dependencies:

   $
   bundle install

3. Use the SDK in your code:

   1
   require 'your_sdk'
   2
   3
   # No auth
   4
   client = YourSdk::Client.new
   5
   6
   # With bearer auth
   7
   client = YourSdk::Client.new(token: 'YOUR_TOKEN')
   8
   9
   # With API key / basic auth
   10
   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:

1
gem 'your-sdk', git: 'https://github.com/your-org/your-sdk.git'
2
3
# Or specify a branch/tag/commit
4
gem 'your-sdk', git: 'https://github.com/your-org/your-sdk.git', branch: 'main'
5
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.
   • Set up your API credentials:

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

2. Prepare your gem for publishing:

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

   $
   gem specification your-sdk-1.0.0.gem

4. Publish to RubyGems:

   $
   gem push your-sdk-1.0.0.gem

5. Verify publication:

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

Publish updates

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

   1
   module YourSdk
   2
     VERSION = "1.0.1"
   3
   end

2. Update CHANGELOG.md with changes.

3. Build and publish:

   $
   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.