-
Notifications
You must be signed in to change notification settings - Fork 7
The most important parts of the API are:
-
Uploading an event. This is the main way that applications and loggers insert time-specific data into DiMe, e.g. "the user has looked at a document", "the user's pulse is so-and-so". Some events contain linked InformationElements, such as the document that was looked at.
-
Fetch an answer. Retrieve an answer (feature) calculated from the uploaded data. Such as the number of documents views yesterday, the average pulse between 9 and 10 this morning, etc.
-
Text search. Search the user's DiMe for InformationElement objects that match a given text.
All API calls are HTTP GET or POST requests to a given DiMe server endpoint:
http://<SERVER_HOST>/api/<ENDPOINT_HERE>
Where <SERVER_HOST> is replaced with the hostname and port number
where the DiMe server is running, typically localhost:8080 when
developing in your local machine.
The payload (if any) is always a JSON formatted object.
At the moment we use simple HTTP username and password. In the future we will likely use OAuth 2.0. Some general API calls may not need authentication. Any calls accessing or uploading data for a given person need authentication.
Below each API endpoint is documented individually.
A way to "ping" the dime-server to see if it's running, and there is network access.
Endpoint: /ping
Method: GET or POST
Authentication: not needed
Returns: A dummy JSON object.
Python example (using the requests library):
r = requests.post(server_url + '/ping',
timeout=10) # e.g. in case of network problems
ok = r.status_code == requests.codes.ok
Example of response:
{
"message": "pong"
}
To upload an event from a logger to be stored in the DiMe server for the authenticated user.
Endpoint: /data/event
Method: POST
Authentication: required
Returns: the uploaded JSON object as it was inserted (possibly some fields may be modified or added in the server)
The POST data is the JSON of the event being uploaded. It is important
that it has a '@type' property that specifies the data type of the
event, the data type should be one of the event classes in DiMe, which
can be found in the source directory:
src/main/java/fi/hiit/dime/data.
You can also see the class hierarchy from the
javadoc page
(requires HIIT username/password).
If you need a new data class, it should be implemented as subclass of the existing ones - please discuss it first e.g. in the #dime channel on Slack or send an email to [email protected].
Here is a quick Python example for a SearchEvent, which is sent to
the /api/data/searchevent end point. A
full working example can be found in the git
repository.
# Set all the standard event fields
payload = {
'@type': 'SearchEvent'
'actor': 'logger-example',
'origin': 'my_machine.hiit.fi',
'type': 'http://www.hiit.fi/ontologies/dime/#ExampleSearchEvent',
'start': '2015-05-08T14:03:42+0300',
'duration': 0,
}
payload['query'] = 'dummy search'
requests.post(server_url + '/data/event',
data=json.dumps(payload),
headers={'content-type': 'application/json'},
auth=(server_username, server_password),
timeout=10)
TODO Add an example with an InformationElement embedded.
Currently we only have implemented a simple method that dumps every InformationElement from DiMe.
Endpoint: /data/informationelement
Method: GET
Authentication: required
Returns: A list of InformationElement objects in an unspecified order.
Here is a quick Python example. A full working example can be found in the git repository.
r = requests.get(server_url + '/data/informationelement',
headers={'content-type': 'application/json'},
auth=(server_username, server_password),
timeout=10)
data = r.json()
# loop through each returned InformationElement and print their URI
for elem in data:
print(elem['uri'])
Perform a text search on existing InformationElements (documents,
posts, etc) in the DiMe. The current backend implementation uses
MongoDB's built-in text query, but we may want to
replace it with Lucene in the future.
Endpoint: /search?query=<QUERY TEXT>
Method: GET
Authentication: required
Returns: A list of InformationElement objects together with a
score indicating the relevance of the object to the search query.
The list is sorted by this score, descending.
Here is a quick Python example which performs a text search for the word "dime". A full working example can be found in the git repository.
r = requests.get(server_url + '/search?query=dime',
headers={'content-type': 'application/json'},
auth=(server_username, server_password),
timeout=10)
Example of returned JSON:
[
{
"plainTextContent": "Some text content\n",
"user": {
"id": "5524d8ede4b06e42cc0e0aca",
"role": "USER",
"username": "testuser"
},
"uri": "file:///home/testuser/some_file.txt",
"type": "http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#TextDocument",
"mimeType": "text/plain",
"timeCreated": 1430142736819,
"id": "d8b5b874e4bae5a6f6260e1042281e91c69d305e",
"timeModified": 1430142736819,
"score": 0.75627613,
"isStoredAs": "http://www.semanticdesktop.org/ontologies/nfo#FileDataObject"
},
{
"plainTextContent": "Some other text content",
"user": {
"id": "5524d8ede4b06e42cc0e0aca",
"role": "USER",
"username": "testuser"
},
"uri": "file:///home/testuser/another_file.txt",
"type": "http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#TextDocument",
"mimeType": "text/plain",
"timeCreated": 1430142737246,
"id": "99db4832be27cff6b08a1f91afbf0401cad49d15",
"timeModified": 1430142737246,
"score": 0.75342464,
"isStoredAs": "http://www.semanticdesktop.org/ontologies/nfo#FileDataObject"
}
]
Endpoint: /answer/<FEATURENAME>
Method: GET
Authentication: required
Returns: a calculated answer (i.e. feature), typically given some GET parameters. Answers could be calculated at given times ("cron"), at each upload, or when needed ("just-in-time"). Currently only the latter implemented...