AL!SE semantic Server contient une large famille de composants qui offrent diverses fonctionnalités sémantiques et intelligentes.

Tout d’abord, chaque développeur entre en contact avec Aglaia, le service de gestion d’interface du framework AL!SE qui héberge un serveur HTTP(S). Il se trouve au-dessus de Leto et fournit une API Web, utilisant des corps HTTP au format JSON.

Le serveur AL!SE fournit :

• Méthodes HTTP pour accéder au serveur (et à la base de données Leto sous-jacente)
• Ajouter/supprimer des informations sur les opérations sur la base de données Leto (par exemple, filigrane PDF)
• Filtrage Semantique
• Gestion de l’accès des utilisateurs via le contrôle de session et les en-têtes de sécurité cryptés
• Connexion/Déconnexion via Leto Nom d’utilisateur et mot de passe
• Connexion/Déconnexion via les informations de licence

La description suivante des méthodes API vous donne les bases pour créer votre propre semanticApp :

Cette version fournit des fonctionnalités pour s’authentifier, gérer les données utilisateur, les applications et les siles et poser des questions.

AL!SE semantic Server contient une large famille de composants qui offrent diverses fonctionnalités sémantiques et intelligentes.

Tout d’abord, chaque développeur entre en contact avec Aglaia, le service de gestion d’interface du framework AL!SE qui héberge un serveur HTTP(S). Il se trouve au-dessus de Leto et fournit une API Web, utilisant des corps HTTP au format JSON.

Authentication

Auth column marked with “X” means the user has to be logged in to perform the request.

AuthMethodPathRequest BodyResponse BodyDescriptionPOST/login{ email, password, ontology[opt]}{ secret, uri }If login credentials match a user, create an authentication secret and return also the user URI along with it.POST/login/license{ deviceUri, serial}{ secret, uri, validFrom, validTo, allowedDevices, registeredDevices }If device URI and corresponding client serial number match the database entries, create an authentication secret and return also the user URI and license data along with it (to check if there was an server-side update).XGET/logoutSecret is invalid from now on.POST/register{ email, password, firstname, lastname }{ email }Create a new deactivated user and an activation key. Send an activation email.XPATCH/register/pronto{ email, password, firstname, lastname }{ email }Create a new activated user.XPOST/fetch-key/redirect{ appId }{ key }Create and return a redirect key for the given app.XPOST/fetch-key/password{ password }{ key }If the password matches the current user, reate and return a password key.POST/mail-key/password{ email }{ email }Create a password key and send it via email.XPOST/mail-key/email{ email }{ email }Create an email key and send it via email.POST/use-key/activation{ key }If the activation key exists (and is not too old), activate the corresponding user.POST/use-key/redirect{ key }{ secret, email, uri }If key is valid, return a new secret along with the user’s email.POST/use-key/password{ key, password }If key is valid, set password of the user.POST/use-key/email{ key }If key is valid, set email of the user.XPATCH/user/password{ password }Changes the password of the authenticated user.

Requests get authorized via HMAC (hash based message authentication). The authentication header is created like this:

secret // came from Aglaia in login response

method // e.g. GET

path // e.g. /v2/apps

user // e.g. user@email.com

nonce // some number, increased in each request

digest = sha256(secret + method + path + nonce)

authenticationHeader = ‘hmac ‘ + user + ‘:’ + nonce + ‘:’ + digest

The request then contains these headers:

GET /v2/apps HTTP/1.1

Host: appx.alise.systems

Authentication: hmac user@email.com:123456:ob23o4h89fo23u4of9h8324oh8f

Content-Type: application/json

Aglaia uses this information to do the following:

• use the user name to get its current secrets from session
• use the host to reduce the amount of possible secrets (secrets are only valid for one app)
• check if the nonce is higher than the stored last nonce for the secret
• build the digest from secret, method, path, date and nonce and compare it to the digest in the request

After that, the request is either rejected or the session is retrieved successfully.

Role Unique

Un utilisateur peut gérer des rôles et leur attribuer d’autres utilisateurs.

AuthMethodPathRequest BodyResponse BodyDescriptionXPOST/role{ roleId, readSlinks[opt], writeSlinks[opt], superRoleId[opt] }RoleCreate role and return Role details.XPATCH/role/{roleId}{ roleId, … }RoleChange role details, e. g. to assign / unassign siles.XGET/role/{roleId}RoleRetrieve role details.

Role Multiple

AuthMethodPathRequest BodyResponse BodyDescriptionXGET/roles[ Role, … ]Return all active roles of the user with their details.

Application Unique
Un utilisateur peut gerer des application et leur attribuer d’autre utilisateurs

AuthMethodPathRequest BodyResponse BodyDescriptionXPOST/app{ appId, appPath, ontPath }AppCreate app for specified repository and return app details.XPATCH/app/{appId}{ users, … }AppChange app details, e. g. to assign / unassign users.XGET/app/{appId}AppRetrieve app details.

Application Multiple

AuthMethodPathRequest BodyResponse BodyDescriptionXGET/apps[ App, … ]Return all active apps of the user with their details.

Ontologies

The OWL-files used for storing data can be retrieved in binary (Base64) form via the API. One method provides getting the identifying URIs of the ontologies, the other one is for retrieving the specified ontology OWL.

AuthMethodPathRequest BodyResponse BodyDescriptionGET/ontology/list[ uri_1, uri_2, … ]Return all Ontology URIs wihtin a JSON Array.POST/ontology/owl{ uri }{ uri, owl }Returns the Ontology URI as well as the Base64-coded owl file.

Spécifications de l’ontologie

The API provides funcitionality to retrieve single specifications from the used ontology.

AuthMethodPathRequest BodyResponse BodyDescriptionGET/category/children/{category}[category1, category2, … ]Return all subcategories of the provided {category} name (excluding this super category)

(Re) Activation de License

Étant donné que les silos de licences ne doivent pas nécessiter un accès autorisé par le nom d’utilisateur, ils disposent de leur propre fonction API. Cependant, l’utilisateur doit s’autoriser avec diverses données qui seront vérifiées sur le serveur.

AuthMethodPathRequest BodyResponse BodyDescriptionPOST/license/activate/{licenseId}{ Bezeichnung, Seriennummer, Plattform, Mitarbeiter[opt] }[ key ]Returns the (encrypted) license key. Serial number and plattform info should be automatically grabbed by the client.POST/license/reactivate/{licenseId}{ Seriennummer }{ key }Returns the (encrypted) license key.

Siles

Les siles sont des objets spécifiés par leur URI et contiennent des données d’utilisation, une étiquette lisible par l’homme (ou consultable) peut être spécifiée. Les attributs, catégories et liens (liens sémantiques) vers d’autres objets sont appelés métadonnées. De plus, un Sile peut contenir du contenu binaire (par exemple une image).

Paramètres de requête de sile

Les appels d’API suivants (à l’exception de DELETE) renvoient toujours un sile (ou, en utilisant le filtre, plusieurs siles) dans lequel la quantité d’informations contenues peut être spécifiée à l’aide d’un paramètre de requête : ajoutez simplement ?content= et une valeur correspondante au fin de l’appel API.

Specifier IDReturned Contenturi (only multiple siles)JSON Array with URIsdate (only multiple siles)JSON Array with JSONObjects containing URI and according update datelabeluri and labelmetadatauri, label, attributes, categories and slinks (default)binaryuri, label and dataallcomplete sile as specified in Sile structure below

For example, GET /sile/uri:example1234?content=binary will return a JSON object with information from the sile with URI=uri:example1234. It will contain the URI, the label and the binary data as Base64-encoded String.

If the query parameter is not defined, the default value (metadata) will be used. Using more query parameters (as it is possible when filtering and retrieving multiple siles, see below), query parameters are seperated by “&”.

Sile unique

MethodPathBodyDescriptionGET/sile/{id}Get sile with this IDPOST/sileSileCreate sile for unspecified IDPATCH/sile/{id}{ …changes }Change the given values in the sile with this IDDELETE/sile/{id}Delete sile with this ID (or keep but set ‘deleted’ timestamp)

La réponse est toujours la dernière représentation JSON du sile, contenant ses classes et son ID.

Structure de Sile

{

“uri”: “234r-23s2-234r-df54”,

“label”: “Sile Label”,

“binaryArray”: “lsadf89a43q4…”,

“attributes”: {

“attributeLabel1”: [

“Value 1”,

“Value 2”

],

…

},

“categories”: [

“category1”,

“category2”,

…

],

“slinks”: {

“dependsOn”: [

{

“uri”: “h39k-i9jn-826j-52ee”,

“label”: “Linked sile 1”

},

…

],

…

}

}

Siles Multiple

Des paramètres de requête supplémentaires « limit » et « offset » sont autorisés pour éviter les gros morceaux de données. Ils sont séparés par un « & ». (Exemple : POST /sile/filter/{filter}?limit=10&offset=20&content=label)

AuthMethodPathRequest BodyResponse BodyDescriptionXPOST/sile/filter{filter}[siles]Returns an array of siles that match the specified filterXPOST/sile/filter/uris[“uri_1”, “uri_2”, …][siles]Returns an array of siles that match the specified uris

The response is an array of all matching siles. It is crucial that every JSON Object contains exactly one filter.

Structure de filtre

[

{

“and”: [

{

“or”: [

{

“type”: “category”,

“label”: “Person”

},

{

“type”: “category”,

“label”: “Topic”

},

{

“type”: “attributetypevalue”,

“label”: “FirstName”,

“value”: “Franz”

}

]

},

{

“type”: “attributetyperange”,

“label”: “AvgHeartRate”,

“minvalue”: “80”,

“maxvalue”: “120”

}

…

]

},

{

“or”: [

…

]

},

{

“not”: {

“type”: “category”,

“label”: “Company”

}

},

…

]

AND and OR filters are compound filters and each contain an array of atomic or futher compound filters. The JSON array transmitted represents an AND filter. The NOT filter negates results of an underlying filter.

Atomic Filter types

The following atomic filters are available, ‘X’s denote required JSON attributes.

typesileurilabelvalueminvaluemaxvaluedescriptionattributerange–––XXAn attribute range filter selects siles which are annotated with an attribute (of any type) whose value is within a specific rangeattributetype–X–––An attribute type filter passes all siles that have at least one attribute with the specified attribute type URI, regardless of its value and datatypeattributetyperange–X–XXAn attribute type range filter selects siles which are annotated with a specific attribute type and a value that is within a specific rangeattributetypevalue–XX––Extends the AttributeFilter by not only considering the attribute type but also its value (ie. textual representation of the value and the datatype URI)category–X–––Checks whether a sile is annotated with a specific categoryfulltextpattern––X––A TagPatternFilter matches tag annotations based on a regular expression pattern. A tag pattern filter is case-insensitive per defaultlabelvalue––X––A NotFilter inverts the selection of the underlying (atomic) filternull–––––A NullFilter holds no specific information and matches for all silessileinoutboundX––––A SileInOutboundFilter is a filter that checks for siles that are slinked by, or that slink to, the specified silesileinboundX––––A SileInboundFilter is a filter that checks for siles that slink to the the searched silesileoutboundX––––A SileOutboundFilter is a filter that checks for siles that are slinked by the searched silesileslinkinboundXX–––A SileSlinkInboundFilter is a filter that checks for siles that are “incoming” linked by a specified other sile with a specified slink typesileslinkoutboundXX–––A SileSlinkOutboundFilter is a filter that checks for siles that link to a specified other sile with a specified slink typeslinkinoutbound–X–––A SlinkInOutboundFilter is a filter that searches for siles that are slinked to or from by a specified slink typeslinkinbound–X–––A SlinkInboundFilter is a filter that searches for siles that are slinked to by a specified slink typeslinkoutbound–X–––A SlinkOutboundFilter is a filter that searches for siles that slink to other siles by a specified slink type

Filter query parameters (?key=value)

keytyperequiredDefaultdescriptionlimitintnoinfinityHow many objects should be retrieved in one calloffsetintno0How many objects should be left out before the first one

Links

http://restcookbook.com/HTTP%20Methods/put-vs-post/ – PUT if you know the URL, POST if you don’t https://blog.restcase.com/restful-api-authentication-basics/ – basics of different authorization methods

Notes

According to the redirect pattern, changing/creating requests would respond with the entity’s URL. In our case though, it is more practical to return the entity directly.

A DELETE request returns the latest representation of the deleted entity, because it can be used by the client to undo the operation by a new PUT request.

Concepts + Research

Semdav Research Paper