Ruby SDK

require 'atlas'

# Read the token from the environment - never hard-code it in source.
client = Atlas::Client.new(token: ENV.fetch('ATLAS_TOKEN'))

require 'atlas'

client = Atlas::Client.new(token: ENV.fetch('ATLAS_TOKEN'))

# List endpoints answer an { "items" => [...], "nextCursor" => ... } envelope.
page = client.atlas_get_tasks(query: { limit: 5 })
page['items'].each do |task|
  puts "#{task['id']} #{task['title']}"
end

begin
  client.atlas_post_tasks(body: { title: '' })
rescue Atlas::ForbiddenError => err
  # 403: the token is missing a scope. The scopes are in the problem body.
  puts "need scopes: #{(err.body || {})['requiredScopes']}"
rescue Atlas::UnauthorizedError
  # 401: token invalid or revoked - re-authenticate.
  raise
rescue Atlas::ApiError => err
  # 409 / 422 / 429 and anything else land here with #status set.
  problem = err.body || {}
  warn "#{err.status} #{problem['title']} #{problem['requestId']}"
  (problem['errors'] || []).each { |f| warn "#{f['path']}: #{f['message']}" } if err.status == 422
  raise
end

RETRYABLE = [429, 500, 502, 503, 504].freeze

def with_retries(max_attempts: 5)
  attempt = 0
  begin
    attempt += 1
    yield
  rescue Atlas::ApiError => err
    raise if !RETRYABLE.include?(err.status) || attempt >= max_attempts

    rate_limit = (err.body || {})['rateLimit'] || {}
    # The 429 body carries the authoritative retry delay, in seconds.
    delay = rate_limit['retryAfterSec'] || [2**(attempt - 1), 30].min + rand
    sleep(delay)
    retry
  end
end

page = with_retries { client.atlas_get_tasks(query: { limit: 50 }) }

require 'atlas'
require 'json'
require 'net/http'
require 'securerandom'
require 'uri'

module Atlas
  # The generated client sends a fixed header set; this thin extension adds an
  # Idempotency-Key to writes so a retried request replays (24h) instead of
  # creating a duplicate.
  class IdempotentClient < Client
    def write(method, path, body, key:)
      uri = URI.parse("#{@base_url}#{path}")
      req = Net::HTTP.const_get(method.capitalize).new(uri)
      req['Authorization'] = "Bearer #{@token}"
      req['Content-Type'] = 'application/json'
      req['Idempotency-Key'] = key
      req.body = JSON.generate(body)

      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = uri.scheme == 'https'
      JSON.parse(http.request(req).body)
    end
  end
end

client = Atlas::IdempotentClient.new(token: ENV.fetch('ATLAS_TOKEN'))

# Generate one key per logical write and reuse it on every retry.
key = SecureRandom.uuid
task = client.write('POST', '/tasks', { projectId: 'prj_123', title: 'Ship it' }, key: key)

require 'atlas'

client = Atlas::Client.new(
  token: ENV.fetch('ATLAS_TOKEN'),
  base_url: 'https://api.atlas.app/v1', # override for staging or self-hosted
  open_timeout: 10,                     # seconds to establish the connection
  read_timeout: 30,                     # seconds to wait for the response
)