# Getting Started With Authoritex
## About
An Elixir library for searching and fetching controlled vocabulary authority terms, inspired by the [Samvera Community's](https://github.com/samvera) [Questioning Authority](https://github.com/samvera/questioning_authority).
`Authoritex` provides an [Elixir behaviour](https://elixir-lang.org/getting-started/typespecs-and-behaviours.html#behaviours) that defines a specification for creating authorities. Each authority is a module which has to implement at least 5 public functions: `can_resolve?/1`, `code/0`, `description/0`, `fetch/1`, and `search/2`.
* `can_resolve?/1` Returns true if the module can resolve the given identifier
* `code/0` Returns the unique short code for the authority
* `description/0` Returns a human-readable description of the authority
* `fetch/1` Fetches a label (and optional hint string) for a specified resource
* `search/2` Returns a list of search results (and optional hints) matching a query
## Installation
```elixir
Mix.install([
{:authoritex, "~> 0.7.0"},
{:kino, "~> 0.5.2"}
])
```
## Configuration
```elixir
Application.put_env(:authoritex, :authorities, [
Authoritex.FAST.CorporateName,
Authoritex.FAST.EventName,
Authoritex.FAST.Form,
Authoritex.FAST.Geographic,
Authoritex.FAST.Personal,
Authoritex.FAST.Topical,
Authoritex.FAST.UniformTitle,
Authoritex.FAST,
Authoritex.GeoNames,
Authoritex.Getty.AAT,
Authoritex.Getty.TGN,
Authoritex.Getty.ULAN,
Authoritex.Getty,
Authoritex.LOC.Languages,
Authoritex.LOC.Names,
Authoritex.LOC.SubjectHeadings
])
```
## List configured authorities
`Authoritex.authorities/0` returns a list of tuples describing all configured authorities.
```elixir
Authoritex.authorities()
```
## Fetch records by id
`Authoritex.fetch/1` returns a map with the `:label`, `:id`, `:hint`, and `:qualified_label` for an authority record given an id (must be a string).
```elixir
# Known authority and record identifier
Authoritex.fetch("http://id.loc.gov/authorities/names/no2011087251")
```
`Authoritex.fetch/1` returns the error tuple `{:error, 404}` given an unknown id for a properly configured authority.
```elixir
# Known authority with unknown record identifier
Authoritex.fetch("http://id.loc.gov/authorities/names/unknown-id")
```
`Authoritex.fetch/1` returns the error tuple `{:error, :unknown_authority}` given an id for an unknown authority.
```elixir
# Unknown authority
Authoritex.fetch("http://fake.authority.org/not-a-real-thing")
```
## Search an authority
`Authoritex.search/2` performs a search with an authority and a search term. The following select menu lets you choose a supported authority:
```elixir
search_authority =
Kino.Input.select(
"Select Authority",
[
{"aat", "Getty Art & Architecture Thesaurus (AAT)"},
{"fast", "Faceted Application of Subject Terminology (FAST) -- Base"},
{"fast-corporate-name", "Faceted Application of Subject Terminology -- Corporate Name"},
{"fast-event-name", "Faceted Application of Subject Terminology -- Event Name"},
{"fast-form", "Faceted Application of Subject Terminology -- Form/Genre"},
{"fast-geographic", "Faceted Application of Subject Terminology -- Geographic"},
{"fast-personal", "Faceted Application of Subject Terminology -- Personal"},
{"fast-topical", "Faceted Application of Subject Terminology -- Topical"},
{"fast-uniform-title", "Faceted Application of Subject Terminology -- Uniform Title"},
{"getty", "Getty -- Base"},
{"lclang", "Library of Congress MARC List for Languages"},
{"lcnaf", "Library of Congress Name Authority File"},
{"lcsh", "Library of Congress Subject Headings"},
{"tgn", "Getty Thesaurus of Geographic Names (TGN)"},
{"ulan", "Getty Union List of Artist Names (ULAN)"}
]
)
```
Enter a search term in the text input:
```elixir
search_term = Kino.Input.text("Search term")
```
Perform the search using the values chosen above:
<!-- livebook:{"reevaluate_automatically":true} -->
```elixir
Authoritex.search(Kino.Input.read(search_authority), Kino.Input.read(search_term))
```
`Authoritex.search/3` takes the same arguments as `Authoritex.search/2` along with a third argument (must be an integer) to limit the result count of the search.
```elixir
Authoritex.search("lcsh", "library", 3)
```
```elixir
# Error recevied when searching an unknown authority
Authoritex.search("not-an-authority", "test")
```
## Testing
`Authoritex` provides a mock for testing purposes in consuming applications.
Configure the mock with a few lines of code:
<!-- livebook:{"force_markdown":true} -->
```elixir
# In test.exs:
config :authoritex, authorities: [Authoritex.Mock]
# In test_helper.exs:
Authoritex.Mock.init()
```
Use the `Authoritex.Mock.set_data/1` function to add data for testing purposes, typically in a `setup` block. The example module below demonstrates an `ExUnit` test using the `Authoritex.Mock`. The `Authoritex.Mock.search/1` function returns all mock data regardless of the string passed to the function. (Note: the following code is a code sample that is not runnable like the examples above):
<!-- livebook:{"force_markdown":true} -->
```elixir
defmodule MyTest do
alias Authoritex.Mock
use ExUnit.Case, async: true
@data [
%{
id: "mock:result1",
label: "First Result",
qualified_label: "First Result (1)",
hint: "(1)"
},
%{
id: "mock:result2",
label: "Second Result",
qualified_label: "Second Result (2)",
hint: "(2)"
},
%{id: "mock:result3", label: "Third Result", qualified_label: "Third Result (3)", hint: "(3)"}
]
setup do
Mock.set_data(@data)
:ok
end
test "results" do
with {:ok, results} <- Mock.search("any") do
assert length(results) == length(@data)
end
end
end
```
