Treaty

Explore comprehensive guides and documentation at docs:

• Getting Started - Installation and basic setup
• Core Concepts - Fundamental concepts and architecture
• API Reference - Complete API documentation
• Examples - Real-world usage examples
• Internationalization - I18n and multilingual support
• Full Documentation Index - Complete documentation index

Treaty provides a complete solution for building versioned APIs in Ruby on Rails:

• Type Safety - Enforce strict type checking for request and response data
• API Versioning - Manage multiple concurrent API versions effortlessly
• Unified Architecture - Request blocks, response blocks, and Entity classes share the same validation system
• Entity Classes (DTOs) - Define reusable data transfer objects for better code organization
• Built-in Validation - Validate incoming requests and outgoing responses automatically
• Data Transformation - Transform data seamlessly between different API versions
• Inventory System - Pass controller-specific data to services efficiently
• Deprecation Management - Mark versions as deprecated with flexible conditions
• Internationalization - Full I18n support for multilingual error messages
• Well-documented - Comprehensive guides and examples for every feature

Add Treaty to your Gemfile:

gem "treaty"

Run:

bundle install

Create your first API contract in app/treaties/posts/create_treaty.rb:

module Posts
  class CreateTreaty < ApplicationTreaty
    version 1, default: true do
      request do
        object :post do
          string :title
          string :content
          string :summary, :optional
        end
      end

      response 201 do
        object :post do
          string :id
          string :title
          string :content
          string :summary
          datetime :created_at
        end
      end

      delegate_to Posts::CreateService
    end
  end
end

Define the treaty in your controller app/controllers/posts_controller.rb:

class PostsController < ApplicationController
  # Treaty automatically:
  # 1. Validates incoming parameters according to request definition
  # 2. Calls Posts::CreateService with validated data
  # 3. Validates service response according to response definition
  # 4. Returns transformed data to client
  treaty :create

  # Optional: Provide additional data from controller to service
  treaty :index do
    provide :current_user
    provide :posts, from: :load_posts
  end

  private

  def load_posts
    Post.published.limit(10)
  end
end

We welcome contributions! You can help by:

• Reporting bugs and suggesting features
• Writing code and improving documentation
• Reviewing pull requests
• Sharing your experience with Treaty

Please read our Contributing Guide before submitting a pull request.

Thank you to all contributors who have helped make Treaty better!

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