Welcome to JSON MDQ Server’s documentation!¶
thiss-mdq is a minimal implementation of the metadata query protocol (MDQ) that only supports JSON data. Metadata in discojson format is loaded from a JSON-file referenced by $METADATA. The file is watched for updates and is reloaded automatically. A server is started on $HOST (0.0.0.0) and $PORT (3000). Run it using “npm start” or the supplied Docker container.
Installing and Running thiss-mdq¶
The recommended way to install thiss-mdq is via docker using the supplied Dockerfile:
# docker build -t thiss-mdq:latest
The docker-image can be run thus:
# docker run -d -p 3000:3000 -v /some/where/metadata.json:/etc/metadata.json thiss-mdq:latest
Verify that the container has started by cURL:ing:
# curl -s http://localhost:3000/
The result should include information about the version of thiss-mdq and the number of entities in the metadata set.
There are two backend options: the default lunr-based backend and the redis backend. Setting the environment varialble INDEXER to ‘redis’ turns on the latter.
API¶
The thiss-mdq server implements the metadata query protocol (MDQ) along with a few extensions.
MDQ¶
The following endpoints are specfied by MDQ (using GET requests)
/entities/
- returns all JSON metadata in a single array./entities/{sha1}<sha1 hash of entityID>
- returns a single entity in JSON format
The MDQ protocol specifies standard content negotiation but currently the Accept header is ignored and application/json is always returned. This may change in the future and clients should always set the Accept header to include application/json
. An optional “.json” efile extension in the URL is ignored.
In addition to these endpoints thiss-mdq supports a couple of extensions:
- Search
- WebFinger
- Monitoring
Search¶
Issue a GET request to /entities/?q=<search>
. The result is a (possibly empty) JSON list of entities matching the search query.
WebFinger¶
Issue a GET request to /.well-known/webfinger
. The result is a list of all URIs (all the entities) included in the indexed metadata. This can be used together with curl/wget to mirror the _static_ contents of the mdq instance. It is of course not possible to mirror all possible searches this way.
Monitoring¶
Issue a GET or HEAD request to /status
. The result is a 200 if the metadata index is alive an well and 500 otherwize.
Release Notes¶
Version 1.1.4¶
- escape special characters in plain text queries
Version 1.2.0¶
- pluggable indexing and redis-support from Hannah Sebuliba
Version 1.2.1¶
- bugfixes
Version 1.2.2¶
- updates to the search algorithm to favor more exact searches over less
Version 1.2.3¶
- Integrate stopwords module instead of locally maintained stopwords
Version 1.2.4¶
- Enforce AND-logic for combining multiple search terms
Version 1.2.5¶
- Never treat the first token as a stopword
Version 1.2.6¶
- Reduce index memory footprint
- Use cluster controller for expressjs
Version 1.3.0¶
- Discontinue support for automatic restarts - rely on external restart
- Change tokenizer to split tokens on whitespace only
- Improved i18n-support
- Provide information about metadata mtime in monitor json
Version 1.3.1¶
- Updated and extended status json information: mtime and ctime for the metadata file is reported separately
Version 1.3.2¶
- Avoid including user-supplied data in header values