Purple::Client

Purple::Client is a small DSL that helps you describe HTTP APIs. You define a domain, paths, and response structures, and the library generates handy methods for interacting with your service.

Installation

Add the gem to your project:

bundle add purple-client

Or install it manually with:

gem install purple-client

Usage

Below are some basic examples of how to define requests and call them. Each snippet defines a custom class that inherits from Purple::Client.

Simple GET request

class StatusClient < Purple::Client
  domain 'https://api.example.com'

  path :status do
    response :ok do
      body :default
    end
    root_method :status
  end
end

# Performs GET https://api.example.com/status
StatusClient.status

Path with a dynamic parameter

class JobsClient < Purple::Client
  domain 'https://api.example.com'

  path :jobs do
    path :job_id, is_param: true do
      response :ok do
        body id: Integer, name: String
      end
      root_method :job
    end
  end
end

# Performs GET https://api.example.com/jobs/123
JobsClient.job(123)

Using authorization

class ProfileClient < Purple::Client
  domain 'https://api.example.com'
  authorization :bearer, 'TOKEN'

  path :profile do
    response :ok do
      body :default
    end
    root_method :profile
  end
end

# Authorization header will be sent automatically
ProfileClient.profile

Nested paths

class PostsClient < Purple::Client
  domain 'https://api.example.com'

  path :users do
    path :user_id, is_param: true do
      path :posts do
        response :ok do
          body [{ id: Integer, title: String }]
        end
        root_method :user_posts
      end
    end
  end
end

# Performs GET https://api.example.com/users/7/posts
PostsClient.user_posts(user_id: 7)

Callbacks with additional arguments

class EventsClient < Purple::Client
  domain 'https://api.example.com'

  additional_callback_arguments :resource

  callback do |url, params, headers, response, resource|
    StoreEvent.call(url:, params:, headers:, response:, resource:)
  end

  path :events do
    response :ok do
      body :default
    end
    root_method :events
  end
end

resource = SomeModel.find(1)
EventsClient.events(resource:)

additional_callback_arguments lets you specify parameter names that will be extracted from the call and passed to your callback. In the example above the resource keyword argument is removed from the request parameters, but is available inside the callback so you can associate the stored event with a record of your choice.

Development

After checking out the repo, run bin/setup to install dependencies. Then run rake spec to execute the tests. You can also run bin/console for an interactive prompt to experiment with the library.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, then run bundle exec rake release.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/purple-client. Contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

purple-client

Runtime