Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/samvera/questioning_authority
Question your authorities
https://github.com/samvera/questioning_authority
core-components samvera-community
Last synced: 5 days ago
JSON representation
Question your authorities
- Host: GitHub
- URL: https://github.com/samvera/questioning_authority
- Owner: samvera
- License: other
- Created: 2013-09-16T19:59:48.000Z (about 11 years ago)
- Default Branch: main
- Last Pushed: 2024-10-15T16:16:57.000Z (24 days ago)
- Last Synced: 2024-10-31T10:16:16.882Z (8 days ago)
- Topics: core-components, samvera-community
- Language: Ruby
- Homepage:
- Size: 3.46 MB
- Stars: 54
- Watchers: 70
- Forks: 30
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG-legacy.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Support: SUPPORT.md
Awesome Lists containing this project
- awesome-starred - samvera/questioning_authority - Question your authorities (others)
README
# Questioning Authority
Code:
[![Gem Version](https://badge.fury.io/rb/qa.png)](http://badge.fury.io/rb/qa)
[![Build Status](https://circleci.com/gh/samvera/questioning_authority.svg?style=svg)](https://circleci.com/gh/samvera/questioning_authority)
[![Coverage Status](https://coveralls.io/repos/github/samvera/questioning_authority/badge.svg?branch=main)](https://coveralls.io/github/samvera/questioning_authority?branch=main)Docs:
[![Contribution Guidelines](http://img.shields.io/badge/CONTRIBUTING-Guidelines-blue.svg)](./CONTRIBUTING.md)
[![Apache 2.0 License](http://img.shields.io/badge/APACHE2-license-blue.svg)](./LICENSE)Community Support: [![Samvera Community Slack](https://img.shields.io/badge/samvera-slack-blueviolet)](http://slack.samvera.org/)
You should question your authorities.
--------------------------------------------------------------------------------
## Table of Contents
- [What does this do?](#what-does-this-do)
- [How does it work?](#how-does-it-work)- [Sub-Authorities](#sub-authorities)
- [How do I use this?](#how-do-i-use-this)
- [Basic QA Requests](#basic-qa-requests)
- [Typical JSON Results](#typical-json-results)- [Authority Sources information](#authority-sources-information)
- [Developer Notes](#developer-notes)
- [Compatibility](#compatibility)
- [Product Owner & Maintenance](#product-owner--maintenance)- [Product Owner](#product-owner)
- [Help](#help)
- [Acknowledgments](#acknowledgments)
## Not seeing documentation you used to find in the README?
Much of the documentation has moved to the [Questioning Authority wiki](https://github.com/samvera/questioning_authority/wiki) to allow for better organization. We hope that you will find this easier to use.
--------------------------------------------------------------------------------
## What does this do?
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.
## How does it work?
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 identifierDepending 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.
### Sub-Authorities
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.
## How do I use this?
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!
### Basic QA Requests
These show the basic routing patterns for connecting to authorities. See the [Questioning Authority wiki](https://github.com/samvera/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
```### Typical JSON Results
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"}
]
```# Authority Sources information
See the [Questioning Authority wiki](https://github.com/samvera/questioning_authority/wiki) for documentation on how to connect to the supported authorities, documentation on how to create new authorities, and other useful tips.
# Developer Notes
[How to Contribute](./CONTRIBUTING.md)
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.
## Contributing
If you're working on PR for this project, create a feature branch off of `main`.
This repository follows the [Samvera Community Code of Conduct](https://samvera.atlassian.net/wiki/spaces/samvera/pages/405212316/Code+of+Conduct) and [language recommendations](https://github.com/samvera/maintenance/blob/main/templates/CONTRIBUTING.md#language). Please ***do not*** create a branch called `master` for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.
## Compatibility
This gem works with Rails 5.0-7.0 and Ruby 2.5-3.1, provided the version of Rails supports the version of Ruby.
- Consult `.circleci/config.yml` for a list of supported combinations.
- The combination of Ruby 3.1 and Rails 6.0 comes with three caveats:
- your app will not be able to use `psych 4` (which ordinarily comes with 3.1). See https://bugs.ruby-lang.org/issues/17866 and https://stackoverflow.com/questions/71191685/visit-psych-nodes-alias-unknown-alias-default-psychbadalias/71192990#71192990 for an explanation. One workaround is to modify your app's `Gemfile` to hold back `psych`: `gem 'psych', '< 4'`.
- likewise, you want to add gem 'net-smtp', require: false to your Gemfile to get around the bug described in https://stackoverflow.com/questions/70500220/rails-7-ruby-3-1-loaderror-cannot-load-such-file-net-smtp .
- finally, you may want to opt in to the latest version of "mail". Again, add to your Gemfile the line `gem "mail", ">= 2.8.0.rc1"`.See also `.circleci/config.yml` and `spec/test_app_templates/Gemfile.extra`.
## Product Owner & Maintenance
`qa` was a Core Component of the Samvera Community. Given a decline in available labor required for maintenance, this project no longer has a dedicated Product Owner. The documentation for what this means can be found [here](http://samvera.github.io/core_components.html#requirements-for-a-core-component).
### Product Owner
**Vacant**
_Until a Product Owner has been identified, we ask that you please direct all requests for support, bug reports, and general questions to the [`#dev` Channel on the Samvera Slack](https://samvera.slack.com/app_redirect?channel=dev)._
## Releasing
1. `bundle install`
2. Increase the version number in `lib/qa/version.rb`
3. Increase the same version number in `.github_changelog_generator`
4. Update `CHANGELOG.md` by running this command:```
github_changelog_generator --user samvera --project questioning_authority --token YOUR_GITHUB_TOKEN_HERE
```5. Commit these changes to the main branch
6. Run `rake release`
# Help
The Samvera community is here to help. Please see our [support guide](./SUPPORT.md).
# Acknowledgments
This software has been developed by and is brought to you by the Samvera community. Learn more at the [Samvera website](http://samvera.org/).
![Samvera Logo](https://wiki.duraspace.org/download/thumbnails/87459292/samvera-fall-font2-200w.png?version=1&modificationDate=1498550535816&api=v2)
## Special thanks to...
[Jeremy Friesen](https://github.com/jeremyf) who gave us the name for our gem.