Problem Detail

Build Status Code Climate Dependency Status Gem Version Inline docs Documentation [Gitter][gitter]

Problem Details for HTTP APIs.

A structure to define a problem detail as a way to carry machine-readable details of errors in a HTTP response, to avoid the need to define new error response formats for HTTP APIs.

To read more: Indicating Problems in HTTP APIs.

Supported version: draft-nottingham-http-problem-07.

Rubies

Installation

ProblemDetail is cryptographically signed.

To be sure the gem you install hasn't been tampered with, add my public key (if you haven't already) as a trusted certificate:

$ gem cert --add <(curl -Ls https://raw.github.com/cyril/problem_detail.rb/master/certs/gem-cyril-public_cert.pem)
$ gem install problem_detail -P HighSecurity

The HighSecurity trust profile will verify all gems. All of ProblemDetail's dependencies are signed.

Or add this line to your application's Gemfile:

gem 'problem_detail'

And then execute:

$ bundle

Usage

http_pb = ProblemDetail::Document.new(
  type:     'http://example.com/probs/out-of-credit',
  title:    'You do not have enough credit.',
  detail:   'Your current balance is 30, but that costs 50.',
  instance: 'http://example.net/account/12345/msgs/abc',
  balance:  30,
  accounts: [
    'http://example.net/account/12345',
    'http://example.net/account/67890'
  ]
)

http_pb.type # => #<URI::HTTP http://example.com/probs/out-of-credit>
http_pb.to_h # => {:balance=>30, :accounts=>["http://example.net/account/12345", "http://example.net/account/67890"], :detail=>"Your current balance is 30, but that costs 50.", :instance=>#<URI::HTTP http://example.net/account/12345/msgs/abc>, :title=>"You do not have enough credit.", :type=>#<URI::HTTP http://example.com/probs/out-of-credit>}

Security

As a basic form of security ProblemDetail provides a set of SHA512 checksums for every Gem release. These checksums can be found in the checksum/ directory. Although these checksums do not prevent malicious users from tampering with a built Gem they can be used for basic integrity verification purposes.

The checksum of a file can be checked using the sha512sum command. For example:

$ sha512sum pkg/problem_detail-0.0.1.gem
d12d7d9c2a4fdfe075cbb7a141fa5f2195175891e4098c7e1a28c8bca655ab44fb9d67b6a2e3991d0f852026c5e4537fdf7e314575c68d1c80b3a4b1eb1c041f  pkg/problem_detail-0.0.1.gem

Versioning

ProblemDetail follows Semantic Versioning 2.0.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

See LICENSE.md file.