Ruby

The Ruby SDK publishes to RubyGems. It needs Ruby 3.0 or later, talks to your API over Net::HTTP, and has no runtime gem dependencies.

Install

gem install your-org-api-client

Or in a Gemfile:

gem "your-org-api-client", "~> 1.0"

Options

Set these for Ruby in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.

Client stylechoicedefault: class

class gives callers a client to create. functions gives free functions to import. See client style.

clientStyleByLang.ruby

Namespacechoicedefault: tags

Groups operations by tags, by URL path, or not at all with none.

namespaceByLang.ruby

Method namingchoicedefault: short

short drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.

methodNaming

Argument stylechoicedefault: positional

object takes one parameters object, and positional takes arguments in order. See argument style.

outputByLang.ruby.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.ruby.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.ruby.usageExample

File headerchoicedefault: include

include or omit. Omitting it needs the Enterprise plan. Set for every language at once.

fileHeader

Package name

Gem names are global. The generator normalises your package name to snake case and derives the module from it, so Acme API and acme-api both publish as:

acme_api      gem name (gem install acme_api, require "acme_api")
AcmeApi       module

The client class inside the module is named after your API's title, so an API titled Acme gives AcmeApi::Acme.

Yanking a gem doesn't free the version

RubyGems lets you yank a version, which stops new installs, but the version number stays claimed and the name stays yours forever. See Publishing.

What callers write

require "acme_api"

config = AcmeApi::ClientConfig.new
config.base_url = "https://api.acme.com/v1"
auth = AcmeApi::ClientAuthConfig.new
auth.bearer = ENV.fetch("ACME_TOKEN")
config.auth = auth

acme = AcmeApi::Acme.new(config)

# list_paginated returns an Enumerator that fetches pages as it goes.
acme.users.list_paginated(limit: 100).each do |user|
  puts user.id
end

Parameters are keyword arguments. Failures raise a subclass of AcmeApi::SdkHttpError per common status (SdkNotFoundError, SdkRateLimitError and so on), each carrying status_code and request_id.

Runtime


Requires	Ruby 3.0 or newer
HTTP	`Net::HTTP`
Timeout	30 seconds per attempt
Retries	Up to 3 attempts, with backoff from 500 ms to 8 seconds
Idempotency keys	`POST` and `PATCH`

Those are the defaults. See every setting and retries and timeouts to change them.

Streaming

For an operation that streams:

client.events.stream.each do |event|
  puts event.id
end

Returns an Enumerator, or pass a block directly. See streaming.

Handling errors

begin
  client.users.get(id: "usr_1")
rescue AcmeApi::SdkNotFoundError
  nil
rescue AcmeApi::SdkHttpError => error
  warn "#{error.status_code} #{error.request_id}"
  raise
end

Each common status has its own subclass of SdkHttpError. error.data holds the decoded model, which you can narrow with is_a?. See what's in the package.

Client shape

What these options do across languages.

Publishing

Connect RubyGems and release.