Tutorial

From HNS.dev

To use the HNS.dev API, you will need an account. This tutorial assumes you already have an account, but if you don't you can use the sandbox to follow it.

Authentication

To calculate the cryptographical signature necessary to authenticate to the API, you could use the following PHP code as an example:

$priv = openssl_get_privatekey(file_get_contents($privateKey));
openssl_sign($xmlIn, $key, $priv);
openssl_free_key($priv);
$key = reset(unpack('H*', $key));

$privateKey contains the name of the file containing your RSA private key. The signature will be returned in $key. This value should be passed to the API as the key parameter in the query string.

Basic example

As a simple example, assume we wish to find the names of all persons with the last name Bos. The following query would describe this:

<query>
  <select>usualname</select>
  <select>lastname</select>
  <from>person</from>
  <where>lastname = 'Bos'</where>
</query>

The usualname and lastname fields combine to give us the name of the person, so we select these properties. We are interested in persons, so we select objects from the person table. Finally, we wish to find persons such that their lastname equals Bos, which is described by the given where clause. We may for example get the following response:

<?xml version="1.0" encoding="UTF-8"?>
<query hash="8b69eadda06a8dc63d349d3c8d65ad203b28f517">
<person id="6">
<usualname>Wouter</usualname>
<lastname>Bos</lastname>
</person>
<person id="12">
<usualname>Johan</usualname>
<lastname>Bos</lastname>
</person>
</query>

In this case, the system contains two persons with last name Bos, and it returns the desired properties. It also returns the numerical identifiers of these objects, so we may be able to directly access them at a later time. Also note the hash value, this can be used to retrieve the same result set at a later time.

More advanced example

As a more involved example, we may wish to find a list of persons and the documents they have written who are related to a certain concept. We can use a tag search for this purpose, like for example:

<query>
  <select>usualname</select>
  <select>lastname</select>
  <select>author_of.title</select>
  <from>person</from>
  <where>'socialism' in tags</where>
</query>

In this case, in addition to the name, we also wish to find the titles the person authored. This is achieved using the compound property author_of.title, which finds the title for teach document in the author_of collection of the person. We are looking for persons tagged with the tag socialism. This could for instance give the following results:

<?xml version="1.0" encoding="UTF-8"?>
<query hash="298f84bbe880c82ed667714cc94ee2c3a51b10a1">
<person id="5">
<usualname>Karl</usualname>
<lastname>Marx</lastname>
<author_of>
<document id="6">
<title>Socialist Manifesto</title>
</document>
</author_of>
</person>
<person id="20">
<usualname>Tony</usualname>
<lastname>Blair</lastname>
<author_of>
<document id="5">
<title>Cooking with Tony</title>
</document>
<document id="14">
<title>The Third Way</title>
</document>
</author_of>
</person>
</query>

We have found two persons with the tag socialism, and we get a list of the documents they have written. We can see that these documents are nested inside the related persons, and are listed by their title along with their identifier. Also note that it is possible to get documents that do not match the desired tags, as only the persons are matched against the tags, not the documents.