Client

The client class is the public interface used for interacting with the service. The client will have methods for each operation defined by the API. Clients are 1:1 with a Smithy service shape and its public methods are 1:1 with Smithy operation shapes.

Initialization

The initialize method takes a Config instance and creates a new Client instance. A Seahorse::MiddlewareBuilder object is created for the operation’s middleware stack, and it can take additional, optional dynamic middleware for the Client instance.

def initialize(config = WhiteLabel::Config.new, options = {})
  @config = config
  @middleware = Hearth::MiddlewareBuilder.new(options[:middleware])
  # other instance state
end

Global Middleware

The client exposes a class method that allows for appending middleware to every instance of Client.

@middleware = Seahorse::MiddlewareBuilder.new

def self.middleware
  @middleware
end

Operation Methods

Each Smithy operation shape maps to one operation method in the Client. These operation methods use a static Middleware stack. The middleware stack handles building the request and returning the response data or an error. Additional, optional middleware can be added dynamically to the operation. Streaming operations take a block, and the Hearth::HTTP::Response object will take an output stream.

def my_operation(params = {}, options = {}, &block)
  stack = Seahorse::MiddlewareStack.new
  input = Params::MyOperationInput.build(params)
  stack.use(...)
  stack.use(...)
  stack.use(...)
  apply_middleware(stack, options[:middleware])
  resp = stack.run(
    input: input,
    context: Hearth::Context.new(
      request: Hearth::HTTP::Request.new(url: options.fetch(:endpoint, @config.endpoint)),
      response: Hearth::HTTP::Response.new(body: response_body),
      params: params,
      logger: @config.logger,
      operation_name: :my_operation
    )
  )
  raise resp.error if resp.error
  resp
end

Operation methods take two positional hash parameters, one for API parameters and the other for operation config overrides. However, generated SDKs also support passing params as the operations input type (eg an instance of Types::Input) allowing users to build input using structured classes.

# normal param usage
client.my_operation(param1: p1, param2: p2)

# overriding client options
client.operation(
  { param1: p1, param2: p2 },
  { endpoint: 'new.endpoint.com', middleware: ... }
)