Wrappix

Wrappix is a code generator that creates Ruby API client libraries from a YAML configuration file. It helps you build structured wrappers for REST APIs with minimal effort.

• Complete code generation: Creates all classes and methods needed to interact with a REST API
• Configurable: Define resources, endpoints, and parameters in a simple YAML file
• Multiple authentication types: Supports OAuth, Basic Authentication, and API Keys
• Automatic documentation: Generates README with usage examples and detailed API reference
• Error handling: Integrated HTTP error management with detailed error objects
• Smart object mapping: Converts JSON responses into Ruby objects with nested attribute access
• Built-in caching: Optional caching system for authentication tokens
• Elegant interface: Fluent API inspired by Ruby best practices

Add this line to your Gemfile:

gem 'wrappix'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install wrappix

Wrappix can be used in two primary ways:

1. Generate a standalone API wrapper gem
2. Create an API client within an existing project

# github_api.yml
api_name: github-api
base_url: https://api.github.com
auth_type: oauth
token_url: https://github.com/login/oauth/access_token

resources:
  users:
    endpoints:
      - name: get
        method: get
        path: users/{username}
      - name: list
        method: get
        path: users
        params: true

  repos:
    endpoints:
      - name: list
        method: get
        path: repos
        params: true
      - name: get
        method: get
        path: repos/{owner}/{repo}
      - name: create
        method: post
        path: user/repos

$ wrappix build github_api.yml

require 'github_api'  # Note: require with underscore!

# Configure the client
GithubApi.configure do |config|
  config.client_id = "your_client_id"
  config.client_secret = "your_client_secret"
  config.access_token = "your_access_token"
end

# Initialize the client
client = GithubApi.client

# Get a user
user = client.users.get("octocat")
puts user.name
puts user.location
puts user.public_repos

# List repositories with pagination
repos = client.repos.list({page: 1, per_page: 10})
repos.data.each do |repo|
  puts "#{repo.name}: #{repo.description}"
end

# Check if there are more pages
if repos.next_href
  puts "More repositories available"
end

The YAML configuration file supports the following options:

auth_type: oauth
token_url: https://example.com/oauth/token

auth_type: basic

auth_type: api_key
api_key_header: X-API-Key  # Custom header name (optional)

Resources define the API endpoints that will be available in your client:

resources:
  users:  # Resource name
    endpoints:
      - name: get            # Method name in your code
        method: get          # HTTP method (get, post, put, patch, delete)
        path: users/{id}     # Path with parameters in braces
        params: true         # Whether it accepts query parameters (optional)
        collection: false    # Whether it returns a collection (optional)

      - name: list
        method: get
        path: users
        params: true
        collection: true     # Processes response as a collection

You can configure how responses are mapped to objects:

response_format:
  collection_root: "data"    # JSON key containing the collection items
  item_root: "user"          # JSON key containing single items (optional)
  pagination:
    next_page_key: "next_href"   # JSON key with URL to next page
    total_count_key: "total"     # JSON key with total count
    limit_key: "limit"           # JSON key with page size

The generated client follows a clean architecture pattern:

• Client: Main entry point to the API
• Resources: Classes for each resource (users, repos, etc.)
• Request: Handles HTTP communication
• Object: Maps JSON responses to Ruby objects
• Collection: Handles collections of objects with pagination
• Error: Standardized error handling
• Configuration: Global configuration

After generating your API client, you can further customize it by editing the generated files.

Contributions are welcome:

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

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