indieweb-endpoints-ruby
A Ruby gem for discovering a URL's IndieAuth, Micropub, and Webmention endpoints.
Key Features
- Compliant with Section 4.1 and Section 4.2.2 of the W3C's IndieAuth Working Group Note, Section 5.3 of the W3C's Micropub Recommendation, and Section 3.1.2 of the W3C's Webmention Recommendation.
- Passes all Endpoint Discovery tests on webmention.rocks.
- Supports Ruby 2.4 and newer.
Getting Started
Before installing and using indieweb-endpoints-ruby, you'll want to have Ruby 2.4 (or newer) installed. It's recommended that you use a Ruby version managment tool like rbenv, chruby, or rvm.
indieweb-endpoints-ruby is developed using Ruby 2.4.6 and is additionally tested against Ruby 2.5.5 and 2.6.2 using Travis CI.
Installation
If you're using Bundler, add indieweb-endpoints-ruby to your project's Gemfile
:
source 'https://rubygems.org'
gem 'indieweb-endpoints'
…and hop over to your command prompt and run…
$ bundle install
Usage
Basic Usage
With indieweb-endpoints-ruby added to your project's Gemfile
and installed, you may discover a URL's IndieWeb-relevant endpoints by doing:
require 'indieweb/endpoints'
endpoints = IndieWeb::Endpoints.get('https://aaronparecki.com')
puts endpoints
This example will search https://aaronparecki.com
for valid IndieAuth, Micropub, and Webmention endpoints. In this case, the program returns a Hash
:
{
authorization_endpoint: 'https://aaronparecki.com/auth',
micropub: 'https://aaronparecki.com/micropub',
redirect_uri: nil,
token_endpoint: 'https://aaronparecki.com/auth/token',
webmention: 'https://webmention.io/aaronpk/webmention'
}
Each key in the resulting Hash
will return either a String
representing a URL or nil
. The redirect_uri
key will return either an Array
or nil
since a given URL may register multiple callback URLs.
Advanced Usage
Should the need arise, you may work directly with the IndieWeb::Endpoints::Client
class:
require 'indieweb/endpoints'
client = IndieWeb::Endpoints::Client.new('https://aaronparecki.com')
puts client.response # => HTTP::Response
puts client.endpoints # => Hash
Exception Handling
There are several exceptions that may be raised by indieweb-endpoints-ruby's underlying dependencies. These errors are raised as subclasses of StandardError
.
From jgarber623/absolutely and sporkmonger/addressable:
IndieWeb::Endpoints::InvalidURIError
From httprb/http:
IndieWeb::Endpoints::ConnectionError
IndieWeb::Endpoints::TimeoutError
IndieWeb::Endpoints::TooManyRedirectsError
Contributing
Interested in helping improve indieweb-endpoints-ruby? Awesome! Your help is greatly appreciated. See CONTRIBUTING.md for details.
By contributing to and participating in the development of indieweb-endpoints-ruby, you acknowledge that you have read and agree to the IndieWeb Code of Conduct.
Acknowledgments
indieweb-endpoints-ruby wouldn't exist without IndieAuth, Micropub, and Webmention and the hard work put in by everyone involved in the IndieWeb movement. Additionally, the comprehensive Webmention Endpoint Discovery test suite at webmention.rocks was invaluable in the development of this Ruby gem.
indieweb-endpoints-ruby is written and maintained by Jason Garber.
License
indieweb-endpoints-ruby is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.