-
-
Notifications
You must be signed in to change notification settings - Fork 26
Configuration Design Notes
First some general comments on RESTful APIs and routes:
I think all retrieval/storage should follow RESTful/clean url design principles, and avoid query params as much as possible. Similarly, the assumption should be that back-end services themselves will be providing URLs that adhere to these principles. (That's not to say that Perseids does this fully currently, but if we're designing from scratch we should design right...)
So storage/retrieval requests should generally correspond to HTTP requests:
GET
POST
PUT
PATCH
and possibly
HEAD
DELETE
And information about resources related to the requested resource should be supplied by the back-end service responses via link tags.
Second, configuration must be both at the plugin and the document level and it might make sense to separate these out. Particularly because I think back-end services might use pre-configured templates for app config, but then need to specify per-document config for things like additional services, tag sets, etc.
Also, some subsets of the configuration, such as named tag sets, might themselves be templated (this may be just another way of stating the above though). Ultimately I think we want a system that can support cascading configuration templates. (I'm having some nightmares here about old Ovid .ini configuration files though...)
Finally, some or all document-level config, if do be done in truly RESTful style, should probably be via link relations in responses to GET requests.
I think (but am not sure) this means that we might want to be able to address configuration settings themselves via URIs.
For concrete use cases, maybe we can look at what we currently support with 2 separate editor integrations in Perseids: the Treebank Editor and the OA Annotation Editor.
Perseids is configured with 2 separate urls to the treebank editor:
- an edit mode url
- a read-only mode url
These urls have placeholders for document identifier, sentence identifier and max number of sentences. The Perseids UI completes these links at runtime to provide the user with per-document, per-sentence links to the treebank editor.
On its side, Alpheios is configured with templated URLS and meta tags, into which the query params get inserted upon initialization of the page. These configuration settings tell the app:
- url to GET info about the document including:
- the treebank config file
- the total number of sentences in the document
- the language of the text in the treebank document
- the text direction of the text in the treebank document
- url to GET the sentence itself (note that this is a partial get of a document stored in Perseids
- url to POST a save of the sentence (note that this should be a PATCH)
- url to POST to return to the Perseids UI
- the name of the cookie containing the CSRF token for the Perseids session
- the name of the http header for the CSRF token for the Perseids session
- the max number of sentences available for navigation
- the mode of the editor (read-only or edit)
Note that, of this information, everything supplied in the info output is document-specific.
Perseids is configured with 2 separate urls to the annotation editor:
- an edit mode url
- a read-only mode url
These urls have placeholders for document identifier and annotation uri (the annotation is contained within the document, just as a sentence is within the treebank document). The Perseids UI completes these links at runtime to provide the user with per-document, per-annotation links to the annotation editor.
On its side, the Annotation Editor is configured with templated URLS and meta tags, into which the query params get inserted upon initialization of the page. These configuration settings tell the app:
- url to GET info about the document including:
- the ontology for the oa:isMotivatedBy field
- the tokenizer services for tokenizing the document referenced in annotation targets and bodies
- path to XSLT files for transformation of tokenization output
- cts services for getting information about available annotation body resources
- links to other operations available within Perseids on the target of the annotation
- url to GET the annotation itself (note that this is a partial get of a document stored in Perseids )
- url to POST a save of the annotation (note that this should be a PATCH)
- url to POST to insert a new annotation into the document
- url to POST to return to the Perseids UI
- the name of the cookie containing the CSRF token for the Perseids session
- the name of the http header for the CSRF token for the Perseids session
- the mode of the editor (read-only or edit)
Note that, of this information, everything supplied in the info output is document-specific.
At a general level, on the Perseids side we want to control some aspects of the Arethusa config that is not document specific, but which might be document state specific. I.e. in general how the app looks and functions . In terms of the arethusa config files this might be:
- which state retrievers
- which main view template
- which plugins (but not which retrievers and not which templates or attributes)
We then might want to configure default plugin behavior per language and document state, and even per user or user role, which could include:
- which retrievers the plugin uses
- templates and/or attributes
And then at the document level (i.e. the point of user/browser interaction with Arethusa):
- overrides to default plugin retrievers, templates and attributes
- document-specific URIs for HEAD, GET, POST, PATCH, DELETE
So, the question then is where does the responsibility lie for merging these configurations? I think ideally we would want back-end services to have to know as little as possible about the inner details of Arethusa config, so that if things change, the impact can be localized to Arethusa as much as possible.
I think having Arethusa provide a UI to create and edit these configuration files goes a long way towards addressing this, but am not sure it is fully sufficient. For example, I think we still need to keep a separation between app-level configuration and user-level configuration, that doesn't result in a single merged conf file, because app-level settings could change, and it would be a serious pain to have to proliferate those changes through all the individual user-specific configs.
And then we still need to be able to provide app-instance (i.e. document-level) overrides, ideally? via link tags in the GET response, as mentioned above.
Sorry... ran out of steam here....