You should question your authorities.
- What does this do?
- How does it work?
- How do I use this?
- Authority Sources information
- Developer Notes
- Help
- Acknowledgments
Much of the documentation has moved to the Questioning Authority wiki to allow for better organization. We hope that you will find this easier to use.
Provides a set of uniform RESTful routes to query any controlled vocabulary or set of authority terms. Results are returned in JSON and can be used within the context of a Rails application or any other Ruby environment. Primary examples would include providing auto-complete functionality via Javascript or populating a dropdown menu with a set of terms.
Authorities are defined as classes, each implementing a set of methods allowing a controller to return results from a given vocabulary in the JSON format. The controller does three things:
- provide a list of all terms (if allowed by the class)
- return a set of terms matching a given query
- return the complete information for a specific term given its identifier
Depending on the kind of authority or its API, the controller may not do all of these things such as return a complete list of terms.
Some authorities, such as Library of Congress, allow sub-authorities which is an additional parameter that further defines the kind of authority to use with the context of a larger one.
Add the gem to your Gemfile
gem 'qa'
Run bundler
bundle install
Install the gem to your application
rails generate qa:install
This will copy over some additional config files and add the engine's routes to your config/route.rb
.
Start questioning your authorities!
These show the basic routing patterns for connecting to authorities. See the Questioning Authority wiki documentation for detailed documentation and examples for each authority and local authorities.
Return a complete list of terms:
/qa/terms/:vocab
/qa/terms/:vocab/:subauthority
Return a set of terms matching a given query
/qa/search/:vocab?q=search_term
/qa/search/:vocab/:subauthority?q=search_term
Return the complete information for a specific term given its identifier
/qa/show/:vocab/:id
/qa/show/:vocab/:subauthority/:id
Results are returned in JSON in this format:
[
{"id" : "subject_id_1", "label" : "First labels"},
{"id" : "subject_id_2", "label" : "Printing labels"},
{"id" : "", "label" : "This term has no id number"},
{"id" : "", "label" : "Neither does this"}
]
See the Questioning Authority wiki for documentation on how to connect to the supported authorities, documentation on how to create new authorities, and other useful tips.
To develop this gem, clone the repository, then run:
bundle install
rake ci
This will install the gems, create a dummy application under spec/internal and run the tests. After you've made changes, make sure you've included tests and run the test suite with a new sample application:
rake engine_cart:clean
rake ci
Commit your features into a new branch and submit a pull request.
- Ruby 2.5 or the latest 2.4 version is recommended. Later versions may also work.
- Rails 5 is required. We recommend the latest Rails 5.2 release.
Questioning Authority is a Core Component of the Samvera community. The documentation for what this means can be found here.
The Samvera community is here to help. Please see our support guide.
This software has been developed by and is brought to you by the Samvera community. Learn more at the Samvera website.
Jeremy Friesen who gave us the name for our gem.