Command line client

[nichtich]

I was surprised there is no simple command line client to query a reconciliation endpoint. Following the specification I started to write such client but it looks like the query format differs between specification and implementation. What am I doing wrong?:

curl -X POST "https://wikidata.reconci.link/en/api" -H 'Content-Type: application/json' -d '{"queries":[{"query":"Marx","limit":"10"}]}'

[wetneb]

The syntax you use looks correct if for the draft version of the specs, but the reconciliation service you are querying only supports the protocol version 0.1 and 0.2, which you can see by GETting its manifest https://wikidata.reconci.link/en/api.

[nichtich]

Oh, thanks, I extended my client to support multiple versions! What service can I use to test the draft API? At https://reconciliation-api.github.io/testbench/#/ most services use 0.1 or 0.2 and https://fornpunkt.se/apis/reconciliation/geonames does not work neither.

#!/usr/bin/bash
# Minimal Reconciliation Service API client.
# Requires bash, curl and jq.
# No support of properties, suggest nor data extension
# TODO: add error handling for failed or malformed HTTP response

set -euo pipefail

usage() {
    echo "$0 [options] [queries...]"
    echo "Options:"
    echo "  -a URL     API endpoint URL (required)"
    echo "  -t id      type (optional)"
    echo "  -v version API version (0.1/0.2=default/draft)"
    echo "  -l number  limit (default: 10)"
    echo "  -n         don't execute request but print it"
    echo
    echo "Examples:"
    echo "  $0 -a https://wikidata.reconci.link/en/api"
    echo "  $0 -a https://wikidata.reconci.link/en/api Marx"
    echo "  $0 -a https://services.getty.edu/vocab/reconcile/ -t /aat Maria"
    echo "  $0 -n -v draft \"Emma Goldman\""
    exit
}

api=
limit=10
version=0.2
typeid=
execute=1

[ $# -eq 0 ] && usage

while getopts "a:v:t:l:hn" arg; do
    case "$arg" in
        a) api="$OPTARG";;
        v) version="$OPTARG";;
        t) typeid="$OPTARG";;
        l) limit="$OPTARG";;
        n) execute=;;
        *) usage;;
    esac
done
shift $(($OPTIND - 1))

if [[ ! "$api" =~ ^https?://.* ]]; then
    if [ ! -z "$execute" ]; then    
        echo "Missing API endpoint (-a)"
        exit 1
    fi
fi

if [ "$version" == "draft" ]; then
    api=${api%/}/reconcile
fi

if [ $# -eq 0 ]; then
    if [ -z "$execute" ]; then 
        echo "$api"
    else
        curl -s "$api" | jq .
    fi
else
    queries=$(for query in "$@"; do echo "$query"; done | jq --raw-input .)
    if [ "$version" == "draft" ]; then
        request=$(echo "$queries" | jq --slurp --arg type "$typeid" --arg limit "$limit" \
            '{queries:map({query:.,$limit|tonumber}+if $type!="" then {$type} else {} end)}'
        )
    else
        request=$(echo "$queries" | jq --slurp --arg type "$typeid" --arg limit "$limit" \
            'map({key:.,value:({query:.,limit:($limit|tonumber)}+if $type!="" then {$type} else {} end)})|from_entries'
        )
    fi
    if [ -z "$execute" ]; then
        echo "$request" | jq
    else
        if [ "$version" == "draft" ]; then
            curl -s -X POST "$api" -H 'Content-Type: application/json' -d "$request" | jq
        else
            curl -s -X POST "$api" -d "queries=$request" | jq
        fi
    fi
fi

[wetneb]

I'm not aware of any service that implements the current draft specification so far. It's a moving target, of course.

[nichtich]

I've moved the client to https://github.com/nichtich/reconcile-cli and successfully tested with current draft specification https://reconcile-publish.skohub.io/

[fsteeg]

Client is listed in census: https://reconciliation-api.github.io/census/clients/, closing.

Thank you for your contribution @nichtich!