Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pragmarb/pragma-contract
Like form objects but, you know, for APIs.
https://github.com/pragmarb/pragma-contract
api contract ecosystem pragma ruby ruby-on-rails trailblazer validation
Last synced: about 2 months ago
JSON representation
Like form objects but, you know, for APIs.
- Host: GitHub
- URL: https://github.com/pragmarb/pragma-contract
- Owner: pragmarb
- License: mit
- Created: 2016-11-15T17:32:02.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-01-08T22:47:07.000Z (about 5 years ago)
- Last Synced: 2024-04-24T19:23:50.797Z (9 months ago)
- Topics: api, contract, ecosystem, pragma, ruby, ruby-on-rails, trailblazer, validation
- Language: Ruby
- Homepage:
- Size: 46.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Pragma::Contract
[](https://travis-ci.org/pragmarb/pragma-contract)
[](https://coveralls.io/github/pragmarb/pragma-contract?branch=master)
[](https://codeclimate.com/github/pragmarb/pragma-contract/maintainability)
Contracts are form objects on steroids for your JSON API.
They are built on top of [Reform](https://github.com/apotonick/reform).
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'pragma-contract'
```
And then execute:
```console
$ bundle
```
Or install it yourself as:
```console
$ gem install pragma-contract
```
## Usage
To create a contract, simply inherit from `Pragma::Contract::Base`:
```ruby
module API
module V1
module Article
module Contract
class Base < Pragma::Contract::Base
property :title
property :body
end
end
end
end
end
```
Since Pragma::Contract is built on top of [Reform](https://github.com/apotonick/reform), you should
consult [its documentation](http://trailblazer.to/gems/reform/) for the basic usage of contracts;
the rest of this section only covers the features provided specifically by Pragma::Contract.
### Coercion
Pragma::Contract supports Reform coercion through the [dry-types](https://github.com/dry-rb/dry-types)
gem.
You can access types with the `Pragma::Contract::Types` module.
```ruby
module API
module V1
module Article
module Contract
class Base < Pragma::Contract::Base
property :title, type: Pragma::Contract::Types::Coercible::String
property :body, type: Pragma::Contract::Types::Coercible::String
property :published_at, type: Pragma::Contract::Types::Form::Date
end
end
end
end
end
```
Helpers are also provided as a shorthand syntax:
```ruby
module API
module V1
module Article
module Contract
class Base < Pragma::Contract::Base
property :title, type: coercible(:string)
property :body, type: coercible(:string)
property :published_at, type: form(:date)
end
end
end
end
end
```
### Model finders
This is a common pattern in API contracts:
```ruby
module API
module V1
module Invoice
module Contract
class Base < Pragma::Contract::Base
property :customer
def customer=(val)
super ::Customer.find_by(id: val)
end
end
end
end
end
end
```
Pragma::Contract provides a shorthand syntax:
```ruby
module API
module V1
module Invoice
module Contract
class Base < Pragma::Contract::Base
property :customer, type: Customer
end
end
end
end
end
```
You can also specify a custom column to find by!
```ruby
module API
module V1
module Invoice
module Contract
class Base < Pragma::Contract::Base
property :customer, type: Customer, by: :email
end
end
end
end
end
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-contract.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).