Authority Service Description
=============================
BlackGoat can query remote authority services that expose RESTful APIs. You can
tell BlackGoat how to query an API using a configuration document. This page
describes the convention for writing a service configuration document that
BlackGoat can understand.
The current version of BlackGoat supports public APIs only. Methods like
:ref:`create` will presumably require some form of authentication, so this
specification will be extended in the near future to support various
authentication schemes.
Overview
--------
A service configuration document is a valid JSON document that describes what
methods the service exposes, and how to use those methods.
There are several core :ref:`special` that (ideally) each authority service
will provide and describe, including :ref:`getmethod` and :ref:``searchmethod``.
.. _template:
Template
--------
Many properties of a configuration will use special template declarations to
describe how an endpoint should be called.
``{}`` - Curly braces can be used to indicate where parameters should be
inserted. There are some global variables (e.g. ``endpoint``) that are
available in any template. For method paths, variable names will be
dereferenced against the ``parameters`` defined for that method.
Top-level Properties
--------------------
The following properties should be included at the top level of the document.
.. list-table:: Top-level properties
:widths: 10 5 10 35
:header-rows: 1
* - Property
- Type
- Required
- Description
* - ``name``
- String
- No
- A (brief) name of the authority service. May be used for display.
* - ``description``
- String
- No
- A free-form description of the service. May be used for display.
* - ``documentation``
- String
- Recommended
- The location of human-readable documentation for the service.
* - ``endpoint``
- String
- Yes
- The root endpoint of the service API. This property will be used to build
requests, and can be referenced in path templates as ``{endpoint}``.
* - ``methods``
- Array
- Yes
- This property contains all of the :ref:`methods` offered by the service.
Example
```````
.. code-block:: javascript
{
"name": "Conceptpower",
"description": "Conceptpower authority service",
"documentation": "http://diging.github.io/conceptpower",
"endpoint": "http://chps.asu.edu/conceptpower/rest",
"methods": [...]
}
.. _methods:
Method Descriptions
-------------------
A service configuration can describe an unlimited number of methods. Each method
is represented as an object in the top-level :ref:`methods` property. Each
method should contain the properties shown below. There are several
:ref:`special` whose descriptions, if included, must conform to some additional
constraints.
.. list-table:: General method properties
:widths: 10 5 10 35
:header-rows: 1
* - Property
- Type
- Required
- Description
* - ``name``
- String
- Yes
- An Unix-name for the method.
* - ``description``
- String
- No
- A free-form description of the method. Used for display.
* - ``path``
- :ref:`template`
- Yes
- The location of the method interface relative to ``endpoint``. This can
include parameters described in ``parameters`` (the name provided in
the ``send`` parameter should be used).
* - ``method``
- String
- Yes
- This should be the name of an HTTP method, e.g. "GET", "POST", "PUT",
etc.
* - :ref:`parameters`
- Array
- No
- If the method accepts specific parameters, they should be defined here.
* - :ref:`response`
- Object
- Yes
- Describes how to interpret the response from the method.
Example
```````
.. code-block:: javascript
{
...
"methods": [
{
"name": "get",
"method": "GET",
"path": "{endpoint}/Concept",
"parameters": [ ... ],
"response": { ... }
},
]
}
.. _parameters:
``parameters``
```````````````
The ``parameters`` property should contain descriptions of any parameters that
should be passed to the method. Any parameters not used to render the
``path`` template will be passed in the payload of the request.
Each object in ``parameters`` should include the following properties:
.. list-table:: Properties for parameters
:widths: 10 5 10 35
:header-rows: 1
* - Property
- Type
- Required
- Description
* - ``accept``
- String
- Yes
- The name of the parameter exposed to BlackGoat. If the method is one of
the special methods, the value of this property may be constrained.
May also be used for display purposes.
* - ``send``
- String
- Yes
- The name of the parameter sent to the method. If the parameter is used
in the ``path`` template, this is the name that will be exposed.
Otherwise, this will be used as the parameter name in the request
payload.
* - ``required``
- Boolean
- No
- If not provided, defaults to ``false``.
Example
.......
.. code-block:: javascript
...
"parameters": [
{
"accept": "id",
"send": "sendid",
"required": true
}
...
],
...
.. _response:
``response``
```````````````
The ``response`` property should describe how to parse the response returned
by the service.
The following properties should be included:
.. list-table:: Properties for response
:widths: 10 5 10 35
:header-rows: 1
* - Property
- Type
- Required
- Description
* - ``type``
- String
- Yes
- Should be ``xml`` (implemented) or ``json`` (coming soon).
* - ``path``
- :ref:`paths`
- No
- Describes the starting point for parsing data in the response document.
If not provided, paths in the individual response parameters will be
assumed to start at the root of the document.
* - ``namespaces``
- Array
- No
- Any namespaces used in the response document should be provided here.
Each namespace should be an object with two parameters: ``prefix``
(used in parameter paths) and ``namespace``. For example:
.. code-block:: javascript
"namespaces": [
{
"prefix": "digitalHPS",
"namespace": "http://www.digitalhps.org/"
},
...
]
* - ``parameters``
- Array
- Yes
- Each object in ``parameters`` should contain two properties: ``name``,
which will be the data key exposed to BlackGoat, and ``path``, which
should describe where in the response to find the corresponding value.
See :ref:`paths` for details.
For example:
.. code-block:: javascript
"parameters": [
...
{
"name": "concept_type",
"path": "digitalHPS:type[type_uri]"
},
...
]
.. _paths:
Path
----
When interpreting a response from an API, BlackGoat will use the paths defined
in the method's ``parameters`` property to extract specific pieces of
information.
* ``/`` - Parts (levels) of a path should be separated by the forward slash.
* ``:`` - If ``namespaces`` are defined (see below), the colon should be used
to explicitly declare the namespace of each part of a path. For example,
the path ``digitalHPS:conceptEntry/digitalHPS:lemma`` refers to the ``lemma``
element inside the ``conceptEntry`` element, both of which belong to the
``digitalHPS`` namespace.
* ``[]`` - If the value of interest resides in an attribute of the focal
element, that attribute can be referenced using square braces. Note that this
only applies to the deepest (last) element in the path. This really only
applies to XML response. This should come before the ``*`` and ``|``
operators.
* ``*`` - The asterisk following an element name indicates that there may be
multiple elements that match the path at a given level. If provided in a
parameter description, multiple values will be returned for that field. If
provided in the base ``path`` for a ``response``, then multiple results will
be extracted. The ``*`` should come at the end of the element name, but before
the ``|`` operator.
* ``|`` - If provided after on the last element of the path, indicates that the
value in the target element should be separated into multiple values using
a specific delimiter. For example, ``names|,`` indicates that the value of
the ``names`` element should be split on any commas.
Example
```````
Given the following document:
.. code-block:: xml
43
Bob, Robert, Rob
5
Josephine, Jo
This configuration...
.. code-block:: javascript
"response": {
"type": "xml",
"path": "root/things/thing*",
"parameters": [
{
"name": "monikers",
"path": "names|,"
},
{
"name": "age",
"path": "age[real-age]"
}
]
}
...will extract the following data:
.. code-block:: javascript
[
{
"monikers": [
"Bob",
"Robert",
"Rob"
],
"age": "54"
},
{
"monikers": [
"Jo",
"Josephine"
],
"age": "4"
}
]
.. _special:
Special Methods
---------------
There are a few methods that most authority services will be expected to
provide. Each of these methods has some specific constraints.
.. _getmethod:
``get``
```````
The ``get`` method should yield a data object that represents a single
concept. The configuration for this method **must**...
* accept a parameter called ``id``;
* yield the parameter ``name``.
It **may** also yield the parameters ``description``, ``concept_type``, and
``identities``.
If ``concept_type`` is provided, its value **must** be an URI of a type concept.
If ``identities`` is provided, the values **must** be URIs of other concepts to
which the focal concept is identical. These will be used to automatically
generate identity statements.
.. _searchmethod:
``search``
``````````
The ``search`` method should yield an array of data objects, each of which
represents a single concept. The configuration for this method **must**...
* accept a parameter called ``q``;
* yield multiple results, each of which has the parameters ``name`` and
``identifier``.
It **may** also accept additional parameters.
Each result **may** also contain the parameters ``description``,
``concept_type``, and ``identities``.
If ``concept_type`` is provided, its value **must** be an URI of a type concept.
If ``identities`` is provided, the values **must** be URIs of other concepts to
which the focal concept is identical. These will be used to automatically
generate identity statements.
.. _create:
``create``
``````````
The ``create`` method should accept data that will be used to generate a new
concept in the authority system.
The configuration for this method **must**...
* accept the parameter``name``;
* yield a single data object with the parameters ``name`` and ``identifier``.
It **may** accept additional parameters, such as ``description`` and
``concept_type``.
It **may** also yield the parameters ``description``, ``concept_type``, and
``identities``.
If ``concept_type`` is provided, its value **must** be an URI of a type concept.
If ``identities`` is provided, the values **must** be URIs of other concepts to
which the focal concept is identical. These will be used to automatically
generate identity statements.
Full Example
------------
Here is a full configuration for the `Conceptpower API
`_, with ``get`` and ``search`` methods.
.. code-block:: javascript
{
"name": "Conceptpower",
"description": "Conceptpower authority service",
"documentation": "http://diging.github.io/conceptpower",
"endpoint": "http://chps.asu.edu/conceptpower/rest",
"methods": [
{
"name": "get",
"method": "GET",
"path": "{endpoint}/Concept",
"parameters": [
{
"accept": "id",
"send": "sendid",
"required": true
}
],
"response": {
"type": "xml",
"path": "digitalHPS:conceptEntry",
"namespaces": [
{
"prefix": "digitalHPS",
"namespace": "http://www.digitalhps.org/"
}
],
"parameters": [
{
"name": "name",
"path": "digitalHPS:lemma"
},
{
"name": "description",
"path": "digitalHPS:description"
},
{
"name": "concept_type",
"path": "digitalHPS:type[type_uri]"
},
{
"name": "identities",
"path": "digitalHPS:equal_to|,"
}
]
}
},
{
"name": "search",
"method": "GET",
"path": "{endpoint}/ConceptLookup/{q}/noun",
"parameters": [
{
"accept": "q",
"send": "q",
"required": true
}
],
"response": {
"type": "xml",
"path": "digitalHPS:conceptEntry*",
"namespaces": [
{
"prefix": "digitalHPS",
"namespace": "http://www.digitalhps.org/"
}
],
"parameters": [
{
"name": "name",
"path": "digitalHPS:lemma"
},
{
"name": "description",
"path": "digitalHPS:description"
},
{
"name": "concept_type",
"path": "digitalHPS:type[type_uri]"
},
{
"name": "identifier",
"path": "digitalHPS:id[concept_uri]"
},
{
"name": "identities",
"path": "digitalHPS:equal_to|,"
}
]
}
}
]
}