/
Datafari API

Datafari API

Owned by Cedric
Last updated: 31 Mar, 2025 by Emeric Bernet-Rollande
34 min read

Valid from Datafari 6.2

The documentation below is valid from Datafari 6.2 onwards. Some parts are still under development.

SECURITY: For Datafari Enterprise Edition only: To manage security and user ACLs in results, see this page : https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/783253542

Introduction

The Datafari API is trying to respect the principles of RESTFUL applications as much as possible and use json as the mean to exchange data. This means that everything returned by the API will be JSON, and any payload in POST and PUT requests made to the API will be in JSON too.

On GET and DELETE requests, some parameter may be passed through url parmeters (either as part of the URL or in the search parameter String - anything that is after the “?”)

Prefix

Every endpoint in this API are prefixed by /rest/VX.Y/ where X and Y are the major and minor versions of this API.

Do also remember to add the relevant path to your Datafari web app (https://datafaridomain/Datafari/rest/VX.Y/endpoint)

Response Structure

All responses are formatted using the following template:

{ "status": "OK|ERROR", "content": {} }

In the following, any object presented as the response is showing the format of the content key in the above template.

For errors, the content follows the following structure:

{ "code": {int}, "reason": {String}, "extra": {Object} }

  1. code: an integer using the HTTP response code nomenclature

  2. reason: a String in English giving some details if relevant to help solve the problem or give context

  3. extra: a JSON object providing some extra information from the endpoint if relevant, can be null or empty

Do keep in mind that on some occasions the server might respond with an HTTP error code without any JSON payload, you must handle this case in your applications.

Endpoints

V2.0

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

GET

search/{handler}?{query}

More details about this API further down in this documentation !
Perform a search or suggest query. See below for more explanations.

 

SPECIFIC RESPONSE FORMAT. See below for more explanations.

 

CE

GET

results/export?query={query}&facetQuery[]={facetQuery}&facetField[]={facetField}&fq[]={fq}&sort={sort}&fl={fl}&nbResults={nbResults}&type=excel

More details about this API further down in this documentation !
Create an excel file containing the results of the provided query and query parameters. The number of results is limited by the nbResults parameter. See below for more explanations.

 

A stream of the created export file. See below for more explanations.

 

CE

GET

users/current/history

Retrieve the current user history (past queries information).

 

{ "history":[ { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"training", "num_hit":0 } }, { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"exactContent%3Aenergy OR innovation future", "num_hit":0 } }, { ... }] }

History is an array of object containing the last queries information from the current user. User must be authenticated to have an history, will return an error if not authenticated.

 

CE

GET

users/current/history?query={query}

Retrieve the current user history (past queries information).

Results will be filtered by query in the API.

 

{ "history":[ { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"exactContent:energy OR innovation future", "num_hit":0 } }, { ... }] }

Example : users/current/history?query=exactContent%3Aenergy OR innovation future

History is an array of object containing the last queries information from the current user. User must be authenticated to have an history, will return an error if not authenticated.

The field stored in parameters.query of the returned entries should contain the user query.

 

CE

GET /rest/v2.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v2.0/search/select?q=*:*

Note that {DATAFARI_BASE_URL} is by default of the following shape: [DATAFARI_DOMAIN_NAME]/Datafari

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/noaggregator

/vector

 

suggest

/suggest

/proposals

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

Warning! /stats and /statsQuery handlers are deprecated since Datafari 6.0, and should be removed in Datafari 6.1.

The main handlers to keep in mind are /select and /suggest.

It is also possible to add more allowed handlers. To do it, add them into $DATAFARI_HOME/tomcat/conf/datafari.properties into : userAllowedHandlers property.

Example :

userAllowedHandlers=/newselect

The /select handler is used to perform search queries while the /suggest handler is used to get suggestions for autocomplete.

If you wonder how to format your queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

The /vector handler is used to perform vector search. Vector search features must be enabled before indexing (see https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/3920297985 ). Instead of returning whole documents from the main Solr collection, this handler returns documents snippets from the VectorMain collection. This handler accepts the following parameters:

  • q or queryrag (required): a keywords-based or natural language-based query

  • topK: The number of results. (default: 10)

  • fl: The list of fields that must be returned in the results. The fields must be separated by a coma. ex:
    fl=title,exact_content,url

Example:

GET {DATAFARI_BASE_URL}/rest/v2.0/search/vector?q=who%20are%20France%20Labs%20founders&topK=5&fl=title,exact_content,url

In this example, a vector search wil be processed using the query “who are France Labs founders”, returning title, content and url of the top 5 results.

The /proposals handler works just like /suggest. However, instead of providing autocomplete suggestions, it processes a search based on the query. This one is meant to be used for autoproposals. The service only returns those fields:

  • title

  • preview_content

  • url

Note that we also provide {DATAFARI_BASE_URL}/rest/v2.0/search/noaggregator that does exactly the same thing as the search API, except that there is no aggregation on it to avoid infinite loops when using the aggregator mode.

Response format

The response format of this endpoint does not follow the standard response format of this API.

The payload of the response is the response from solr (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

For each document in the response, they have two fields for the url:

  1. doc.url : the original url of the document

  2. doc.click_url : The url to use for the href link to send the user to the document (and will track user clicks to get statistics in the search engine)

Starting from Datafari 6.1, there is also a specific url to open folder links :

  1. doc.folder_url

GET /rest/v2.0/results/export?*

This is the endpoint to perform an export of the result of a provided query. Here are the parameters to provide:

  • query: the main query to perform. ex:
    query=*:*

  • facetQuery: An array containing all the facet queries. ex:
    facetQuery[]={!key=From%20100KB%20To%2010MB}original_file_size:[102400 TO 10485760]&facetQuery[]={!key=More%20Than%2010MB}original_file_size:[10485760 TO *]

  • facetField: An array containing all the facet fields. ex:
    facetField[]=extension&facetField[]=language&facetField[]=source

  • fq: An array containing all the active filter queries. ex:
    fq[]={!tag=query}original_file_size:[102400 TO 10485760]&fq[]={!tag=author}(author:"agence de l'eau artois picardie")

  • sort: The sort method to apply to results, can be either "score desc", or "score asc". ex:
    sort=score desc

  • fl: The list of fields that must be returned in the results. The fields must be separated by a coma. ex:
    fl=title,last_modified,url

  • nbResults: The number of results that the export file must contain. ex:
    nbResults=500
    Be careful with this parameter, because the higher is the number, the more the query will take time and the export file will be big

  • type: The type of the export file to generate. Currently (December 2022) the only supported type is “excel”:
    type=excel

Here is an example of a GET request to the export API:

/rest/v2.0/results/export?query=*:*&facetQuery[]=original_file_size:[102400 TO 10485760]&facetQuery[]=original_file_size:[10485760 TO *]&facetField[]=extension&facetField[]=language&fq[]=original_file_size:[102400 TO 10485760]&sort=score desc&fl=title,last_modified,url&nbResults=10&type=excel

The response of this endpoint is a bytes input stream of the generated export file. In a standard web browser like chrome, it will trigger a download process

V1.0

Bellow is a set of API endpoints that are implemented or in the roadmap. Endpoints that are not implemented are clearly identified by the “NOT IMPLEMENTED” string in the response column. Those endpoints return a 501 HTTP Response code when queried (which is the code for the NOT_IMPLEMENTED http error). For implemented endpoints, query body and format for the content object of the response in case of success are provided.

The auth endpoint is particular and can't be called using AJAX, the user must be redirected to this endpoint and Datafari will redirect the user back to the callback URL once the authentication is performed successfully.

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

GET

users/current

Get the information about the currently connected user

 

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current

Update user information, only the language and uiConfig can be modified.

{ "lang"?:{String} "uiConfig"?: {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Both arguments are optional, if none is provided, nothing is done

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

 

Authenticated User

GET

users/current/uiconfig

Get only the uiConfig for the current user

 

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current/uiconfig

Update only the uiConfig for the current user

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

 

{ "uiConfig": {Obj} }

echos the query

Authenticated User

GET

status/features/favorites

Provide the status of the favorite feature

 

{ "activated":{boolean as String} }

 

GET

users/current/alerts

Provide the list of alerts for the current user

 

{ "alerts":[ { "_id":{String}, "core":{String}, "frequency":{String}, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String - optional}, "user": {String - username} }, ... ] }

Authenticated User

POST

users/current/alerts

Create a new alert for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String}, }

Echos the parameters with the created id

Authenticated User

PUT

users/current/alerts/{id}

Updates alert {id} for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

Response should be an echo of the query with an updated ID

Authenticated User

DELETE

users/current/alerts/{id}

Delete alert {id} from the current user alerts

 

{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

The deleted alert object is returned.

Authenticated User

GET

users/current/savedsearches

Retrieve the set of saved searches for the current user

 

{ "savedsearches":[ { "name":{String}, "search":{String}, }, ... ] }

 

POST

users/current/savedsearches

Creates a new saved search for the current user

{ "name":{String - the name}, "search":{String - the query}, }
{ "name":{String - the name}, "search":{String - the query}, }

Echos the parameters

 

PUT

users/current/savedsearches/{savedSearchname}

Updates the saved search with name savedSearchname for the current user

{ "name":{String - the name}, "search":{String - the query}, }

The name property of the object must be the same as the name provided in the URL

{ "name":{String - the name}, "search":{String - the query}, }

Echos the saved data

 

DELETE

users/current/savedseaches/{savedSearchname}

Delete the saved search with name savedSearchname for the current user.

 

{ "name":{String - the name}, "search":{String - the query}, }

Echos the deleted saved search data

 

GET

users/current/favorites

Retrieve the list of favorites for the current user

 

{ "favorites":[ { "id": {String}, "title": {String} }, ... ] }

 

POST

users/current/favorites

Adds a new favorite for the current user

{ "id":{String}, "title":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the saved favorite

 

DELETE

users/current/favorites

Delete the favorite with the id provided in the body for the current user.

{ "id":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the deleted favorite

 

GET

goldenqueries

Retrieve the list of saved golden queries

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

goldenqueries/{id}

Retrieve the information of a particular golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

POST

goldenqueries

Creates a new golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

PUT

goldenqueries/{id}

Updates the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

DELETE

goldenqueries/{id}

Deletes the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

fields/info

Get the list of information about solr fields that can be used.

 

{ "fields":[ {"indexed":true,"stored":false,"name":"artifact_assignees_search","type":"text_general","multiValued":true}, ... ] }

 

GET

fields/exact

Get the list of exact search fields (for advanced search)

 

{ "exactFieldsList":[ {}, ... ] }

 

GET

fields/autocomplete

Get the list of fields for which an autocomplete is available (for advanced search)

 

{ autocompleteFields:{ "solr_field_name":"suggester", ... }

 

GET

fields/label

Get the list of mappings between fields name and labels (for display purposes)

 

{ mappingFieldNameValues:{ "solr_field_name":"label", ... }

 

GET

fields/fixedvalues

Get the list of fields that can only take fixed values and their list of possible values (for advanced search)

 

{ "exactFieldsList":{ "fieldname":[{"value":"solr_field_value","label":"label_todisplay"}, "*", ...], ... } }

When an entry in the array is not an object with a value and label key but only a string, it is used both as the value and label

 

GET

help/{locale}

Get the help text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlHelpContent":{html} }

 

GET

privacy/{locale}

Get the privacy text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlPrivacyContent":{html} }

 

GET

licence

Get information about the licence currently in use. To display warning message when relevant.

 

{ "type":{String}, "contact": {String - email}, "time": {String - valid | ending | overdue | expired}, "files": {String - valid | ending | overdue | expired}, "users": {String - valid | ending | overdue | expired} }

Users information is shown to administrator users only

ending = close to reach the limit of the licence
overdue = licence limit has been reached but the system still function for a limited time
expired = the system or at least part of it has stopped until a proper licence is issued

 

GET

aggregator

Get the list of sources available in the aggregator when it is active.

 

{ "aggregatorList": [ { "label": str, ?selected: bool } ] }

An array of available aggregated sources for the current user, each element of the array is an object with the following properties:

  • label: used for display and for addition to the query when one wants to query specific sources. If no list of source is added to the query and the aggregator is active, the default list of sources for the user will be used.

  • selected: optional, usually only present if set to true. Tells which sources are part of the default set of search sources for the current user.

Returns and empty array if the aggregator feature is not active.

 

GET

sources/external

Get the list of external source available

 

NOT IMPLEMENTED

 

GET

URL?url=blablabla

Redirects to the required document, used to send the user to the source document when he clicks on the result.

 

NOT IMPLEMENTED

 

GET

search/{handler}?{query}

Perform a search or suggest query.

 

SPECIFIC RESPONSE FORMAT

 

GET

results/export

Get the csv version of the results for export

 

NOT IMPLEMENTED

 

GET

results/download?file=path

download the provided file from the results

 

NOT IMPLEMENTED

 

GET

auth?callback=url

 

User must be redirected to this URL, Datafari will redirect to the callback URL after the auth process is complete.

User redirected to the callback URL

 

Keep in mind that for now, this API is meant to cover standard users actions only. Admin actions are out of the scope for the time being.

Details

Special cases

Auth

For use authentication, the browser must be redirected to the auth endpoint. Once Datafari has finished the authentication process, the user is redirected to the callback URL provided as a URL parameter.

The URL to redirect the user to is:

{DATAFARI_BASE_URL}/rest/v1.0/auth?callback=url

Provide any URL you need the user to be send back to as the value for the callback parameter.

GET /rest/v1.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v1.0/search/select?q=*:*

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/

suggest

/suggest

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

Warning! /stats and /statsQuery handlers are deprecated since Datafari 6.0, and should be removed in Datafari 6.1.

The main handlers to keep in mind are /select and /suggest.

The /select handlers is used to perform search queries while the suggest handler is used to get suggestions for autocomplete.

For how to format you queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

Response format

The response format of this endpoint does not follow the standard response format of this API. The payload of the response is the response from solr unfiltered (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

Standard endpoints

GET /rest/v1.0/users/current

This endpoints returns the information about the currently connected user in the following form:

{ "name": {username} "roles": [{roles list}] "lang": {locale} }

Exemple request / response

Request:

curl "https://localhost/Datafari/rest/v1_0/current"

Response:

HTTP 200/OK { "status": "OK", "content": { "name": "admin" "roles": ["SearchAdmin"] "lang": "en" } }

 

 

 

 

Valid from Datafari 6.0 up to 6.1

The documentation below is valid from Datafari 6.0 up to 6.0.

SECURITY: For Datafari Enterprise Edition only: To manage security and user ACLs in results, see this page : https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/783253542

Introduction

The Datafari API is trying to respect the principles of RESTFUL applications as much as possible and use json as the mean to exchange data. This means that everything returned by the API will be JSON, and any payload in POST and PUT requests made to the API will be in JSON too.

On GET and DELETE requests, some parameter may be passed through url parmeters (either as part of the URL or in the search parameter String - anything that is after the “?”)

Prefix

Every endpoint in this API are prefixed by /rest/VX.Y/ where X and Y are the major and minor versions of this API.

Do also remember to add the relevant path to your Datafari web app (https://datafaridomain/Datafari/rest/VX.Y/endpoint)

Response Structure

All responses are formatted using the following template:

{ "status": "OK|ERROR", "content": {} }

In the following, any object presented as the response is showing the format of the content key in the above template.

For errors, the content follows the following structure:

{ "code": {int}, "reason": {String}, "extra": {Object} }

  1. code: an integer using the HTTP response code nomenclature

  2. reason: a String in English giving some details if relevant to help solve the problem or give context

  3. extra: a JSON object providing some extra information from the endpoint if relevant, can be null or empty

Do keep in mind that on some occasions the server might respond with an HTTP error code without any JSON payload, you must handle this case in your applications.

Endpoints

V2.0

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

GET

search/{handler}?{query}

More details about this API further down in this documentation !
Perform a search or suggest query. See below for more explanations.

 

SPECIFIC RESPONSE FORMAT. See below for more explanations.

 

CE

GET

results/export?query={query}&facetQuery[]={facetQuery}&facetField[]={facetField}&fq[]={fq}&sort={sort}&fl={fl}&nbResults={nbResults}&type=excel

More details about this API further down in this documentation !
Create an excel file containing the results of the provided query and query parameters. The number of results is limited by the nbResults parameter. See below for more explanations.

 

A stream of the created export file. See below for more explanations.

 

CE

GET

users/current/history

Retrieve the current user history (past queries information).

 

{ "history":[ { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"training", "num_hit":0 } }, { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"exactContent%3Aenergy OR innovation future", "num_hit":0 } }, { ... }] }

History is an array of object containing the last queries information from the current user. User must be authenticated to have an history, will return an error if not authenticated.

 

CE

GET

users/current/history?query={query}

Retrieve the current user history (past queries information).

Results will be filtered by query in the API.

 

{ "history":[ { "action":"SEARCH", "query_id": ..., "time_stamp":..., "user_id":..., "parameters":{ "query":"exactContent:energy OR innovation future", "num_hit":0 } }, { ... }] }

Example : users/current/history?query=exactContent%3Aenergy OR innovation future

History is an array of object containing the last queries information from the current user. User must be authenticated to have an history, will return an error if not authenticated.

The field stored in parameters.query of the returned entries should contain the user query.

 

CE

GET /rest/v2.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v2.0/search/select?q=*:*

Note that {DATAFARI_BASE_URL} is by default of the following shape: [DATAFARI_DOMAIN_NAME]/Datafari

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/noaggregator

 

suggest

/suggest

/proposals

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

Warning! /stats and /statsQuery handlers are deprecated since Datafari 6.0, and should be removed in Datafari 6.1.

The main handlers to keep in mind are /select and /suggest.

It is also possible to add more allowed handlers. To do it, add them into $DATAFARI_HOME/tomcat/conf/datafari.properties into : userAllowedHandlers property.

Example :

userAllowedHandlers=/newselect

The /select handler is used to perform search queries while the /suggest handler is used to get suggestions for autocomplete.

If you wonder how to format your queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

The /proposals handler works just like /suggest. However, instead of providing autocomplete suggestions, it processes a search based on the query. This one is meant to be used for autoproposals. The service only returns those fields:

  • title

  • preview_content

  • url

Note that we also provide {DATAFARI_BASE_URL}/rest/v2.0/search/noaggregator that does exactly the same thing as the search API, except that there is no aggregation on it to avoid infinite loops when using the aggregator mode.

Response format

The response format of this endpoint does not follow the standard response format of this API.

The payload of the response is the response from solr (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

For each document in the response, they have two fields for the url:

  1. doc.url : the original url of the document

  2. doc.click_url : The url to use for the href link to send the user to the document (and will track user clicks to get statistics in the search engine)

Starting from Datafari 6.1, there is also a specific url to open folder links :

  1. doc.folder_url

GET /rest/v2.0/results/export?*

This is the endpoint to perform an export of the result of a provided query. Here are the parameters to provide:

  • query: the main query to perform. ex:
    query=*:*

  • facetQuery: An array containing all the facet queries. ex:
    facetQuery[]={!key=From%20100KB%20To%2010MB}original_file_size:[102400 TO 10485760]&facetQuery[]={!key=More%20Than%2010MB}original_file_size:[10485760 TO *]

  • facetField: An array containing all the facet fields. ex:
    facetField[]=extension&facetField[]=language&facetField[]=source

  • fq: An array containing all the active filter queries. ex:
    fq[]={!tag=query}original_file_size:[102400 TO 10485760]&fq[]={!tag=author}(author:"agence de l'eau artois picardie")

  • sort: The sort method to apply to results, can be either "score desc", or "score asc". ex:
    sort=score desc

  • fl: The list of fields that must be returned in the results. The fields must be separated by a coma. ex:
    fl=title,last_modified,url

  • nbResults: The number of results that the export file must contain. ex:
    nbResults=500
    Be careful with this parameter, because the higher is the number, the more the query will take time and the export file will be big

  • type: The type of the export file to generate. Currently (December 2022) the only supported type is “excel”:
    type=excel

Here is an example of a GET request to the export API:

/rest/v2.0/results/export?query=*:*&facetQuery[]=original_file_size:[102400 TO 10485760]&facetQuery[]=original_file_size:[10485760 TO *]&facetField[]=extension&facetField[]=language&fq[]=original_file_size:[102400 TO 10485760]&sort=score desc&fl=title,last_modified,url&nbResults=10&type=excel

The response of this endpoint is a bytes input stream of the generated export file. In a standard web browser like chrome, it will trigger a download process

V1.0

Bellow is a set of API endpoints that are implemented or in the roadmap. Endpoints that are not implemented are clearly identified by the “NOT IMPLEMENTED” string in the response column. Those endpoints return a 501 HTTP Response code when queried (which is the code for the NOT_IMPLEMENTED http error). For implemented endpoints, query body and format for the content object of the response in case of success are provided.

The auth endpoint is particular and can't be called using AJAX, the user must be redirected to this endpoint and Datafari will redirect the user back to the callback URL once the authentication is performed successfully.

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

GET

users/current

Get the information about the currently connected user

 

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current

Update user information, only the language and uiConfig can be modified.

{ "lang"?:{String} "uiConfig"?: {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Both arguments are optional, if none is provided, nothing is done

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

 

Authenticated User

GET

users/current/uiconfig

Get only the uiConfig for the current user

 

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current/uiconfig

Update only the uiConfig for the current user

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

 

{ "uiConfig": {Obj} }

echos the query

Authenticated User

GET

status/features/favorites

Provide the status of the favorite feature

 

{ "activated":{boolean as String} }

 

GET

users/current/alerts

Provide the list of alerts for the current user

 

{ "alerts":[ { "_id":{String}, "core":{String}, "frequency":{String}, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String - optional}, "user": {String - username} }, ... ] }

Authenticated User

POST

users/current/alerts

Create a new alert for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String}, }

Echos the parameters with the created id

Authenticated User

PUT

users/current/alerts/{id}

Updates alert {id} for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

Response should be an echo of the query with an updated ID

Authenticated User

DELETE

users/current/alerts/{id}

Delete alert {id} from the current user alerts

 

{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

The deleted alert object is returned.

Authenticated User

GET

users/current/savedsearches

Retrieve the set of saved searches for the current user

 

{ "savedsearches":[ { "name":{String}, "search":{String}, }, ... ] }

 

POST

users/current/savedsearches

Creates a new saved search for the current user

{ "name":{String - the name}, "search":{String - the query}, }
{ "name":{String - the name}, "search":{String - the query}, }

Echos the parameters

 

PUT

users/current/savedsearches/{savedSearchname}

Updates the saved search with name savedSearchname for the current user

{ "name":{String - the name}, "search":{String - the query}, }

The name property of the object must be the same as the name provided in the URL

{ "name":{String - the name}, "search":{String - the query}, }

Echos the saved data

 

DELETE

users/current/savedseaches/{savedSearchname}

Delete the saved search with name savedSearchname for the current user.

 

{ "name":{String - the name}, "search":{String - the query}, }

Echos the deleted saved search data

 

GET

users/current/favorites

Retrieve the list of favorites for the current user

 

{ "favorites":[ { "id": {String}, "title": {String} }, ... ] }

 

POST

users/current/favorites

Adds a new favorite for the current user

{ "id":{String}, "title":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the saved favorite

 

DELETE

users/current/favorites

Delete the favorite with the id provided in the body for the current user.

{ "id":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the deleted favorite

 

GET

goldenqueries

Retrieve the list of saved golden queries

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

goldenqueries/{id}

Retrieve the information of a particular golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

POST

goldenqueries

Creates a new golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

PUT

goldenqueries/{id}

Updates the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

DELETE

goldenqueries/{id}

Deletes the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

fields/info

Get the list of information about solr fields that can be used.

 

{ "fields":[ {"indexed":true,"stored":false,"name":"artifact_assignees_search","type":"text_general","multiValued":true}, ... ] }

 

GET

fields/exact

Get the list of exact search fields (for advanced search)

 

{ "exactFieldsList":[ {}, ... ] }

 

GET

fields/autocomplete

Get the list of fields for which an autocomplete is available (for advanced search)

 

{ autocompleteFields:{ "solr_field_name":"suggester", ... }

 

GET

fields/label

Get the list of mappings between fields name and labels (for display purposes)

 

{ mappingFieldNameValues:{ "solr_field_name":"label", ... }

 

GET

fields/fixedvalues

Get the list of fields that can only take fixed values and their list of possible values (for advanced search)

 

{ "exactFieldsList":{ "fieldname":[{"value":"solr_field_value","label":"label_todisplay"}, "*", ...], ... } }

When an entry in the array is not an object with a value and label key but only a string, it is used both as the value and label

 

GET

help/{locale}

Get the help text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlHelpContent":{html} }

 

GET

privacy/{locale}

Get the privacy text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlPrivacyContent":{html} }

 

GET

licence

Get information about the licence currently in use. To display warning message when relevant.

 

{ "type":{String}, "contact": {String - email}, "time": {String - valid | ending | overdue | expired}, "files": {String - valid | ending | overdue | expired}, "users": {String - valid | ending | overdue | expired} }

Users information is shown to administrator users only

ending = close to reach the limit of the licence
overdue = licence limit has been reached but the system still function for a limited time
expired = the system or at least part of it has stopped until a proper licence is issued

 

GET

aggregator

Get the list of sources available in the aggregator when it is active.

 

{ "aggregatorList": [ { "label": str, ?selected: bool } ] }

An array of available aggregated sources for the current user, each element of the array is an object with the following properties:

  • label: used for display and for addition to the query when one wants to query specific sources. If no list of source is added to the query and the aggregator is active, the default list of sources for the user will be used.

  • selected: optional, usually only present if set to true. Tells which sources are part of the default set of search sources for the current user.

Returns and empty array if the aggregator feature is not active.

 

GET

sources/external

Get the list of external source available

 

NOT IMPLEMENTED

 

GET

URL?url=blablabla

Redirects to the required document, used to send the user to the source document when he clicks on the result.

 

NOT IMPLEMENTED

 

GET

search/{handler}?{query}

Perform a search or suggest query.

 

SPECIFIC RESPONSE FORMAT

 

GET

results/export

Get the csv version of the results for export

 

NOT IMPLEMENTED

 

GET

results/download?file=path

download the provided file from the results

 

NOT IMPLEMENTED

 

GET

auth?callback=url

 

User must be redirected to this URL, Datafari will redirect to the callback URL after the auth process is complete.

User redirected to the callback URL

 

Keep in mind that for now, this API is meant to cover standard users actions only. Admin actions are out of the scope for the time being.

Details

Special cases

Auth

For use authentication, the browser must be redirected to the auth endpoint. Once Datafari has finished the authentication process, the user is redirected to the callback URL provided as a URL parameter.

The URL to redirect the user to is:

{DATAFARI_BASE_URL}/rest/v1.0/auth?callback=url

Provide any URL you need the user to be send back to as the value for the callback parameter.

GET /rest/v1.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v1.0/search/select?q=*:*

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/

suggest

/suggest

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

Warning! /stats and /statsQuery handlers are deprecated since Datafari 6.0, and should be removed in Datafari 6.1.

The main handlers to keep in mind are /select and /suggest.

The /select handlers is used to perform search queries while the suggest handler is used to get suggestions for autocomplete.

For how to format you queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

Response format

The response format of this endpoint does not follow the standard response format of this API. The payload of the response is the response from solr unfiltered (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

Standard endpoints

GET /rest/v1.0/users/current

This endpoints returns the information about the currently connected user in the following form:

{ "name": {username} "roles": [{roles list}] "lang": {locale} }

Exemple request / response

Request:

curl "https://localhost/Datafari/rest/v1_0/current"

Response:

HTTP 200/OK { "status": "OK", "content": { "name": "admin" "roles": ["SearchAdmin"] "lang": "en" } }

 

Used by default starting from Datafari 5.4 up to 5.5

Some parts are still under development

Introduction

The new Datafari API is trying to respect the principles of RESTFUL applications as much as possible and use json as the mean to exchange data. This means that everything returned by the API will be JSON, and any payload in POST and PUT requests made to the API will be in JSON too.

On GET and DELETE requests, some parameter may be passed through url parmeters (either as part of the URL or in the search parameter String - anything that is after the “?”)

Prefix

Every endpoint in this API are prefixed by /rest/VX.Y/ where X and Y are the major and minor versions of this API.

Do also remember to add the relevant path to your Datafari web app (https://datafaridomain/Datafari/rest/VX.Y/endpoint)

Response Structure

All responses are formatted using the following template:

{ "status": "OK|ERROR", "content": {} }

In the following, any object presented as the response is showing the format of the content key in the above template.

For errors, the content follows the following structure:

{ "code": {int}, "reason": {String}, "extra": {Object} }

  1. code: an integer using the HTTP response code nomenclature

  2. reason: a String in English giving some details if relevant to help solve the problem or give context

  3. extra: a JSON object providing some extra information from the endpoint if relevant, can be null or empty

Do keep in mind that on some occasions the server might respond with an HTTP error code without any JSON payload, you must handle this case in your applications.

Endpoints

V2.0

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

EDITION

GET

search/{handler}?{query}

More details about this API further down in this documentation !
Perform a search or suggest query. See below for more explanations.

 

SPECIFIC RESPONSE FORMAT. See below for more explanations.

 

CE

GET

results/export?query={query}&facetQuery[]={facetQuery}&facetField[]={facetField}&fq[]={fq}&sort={sort}&fl={fl}&nbResults={nbResults}&type=excel

More details about this API further down in this documentation !
Create an excel file containing the results of the provided query and query parameters. The number of results is limited by the nbResults parameter. See below for more explanations.

 

A stream of the created export file. See below for more explanations.

 

CE

GET /rest/v2.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v2.0/search/select?q=*:*

Note that {DATAFARI_BASE_URL} is by default of the following shape: [DATAFARI_DOMAIN_NAME]/Datafari

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/noaggregator

 

suggest

/suggest

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

The main handlers to keep in mind are /select and /suggest.

It is also possible to add more allowed handlers. To do it, add them into $DATAFARI_HOME/tomcat/conf/datafari.properties into : userAllowedHandlers property.

Example :

userAllowedHandlers=/newselect

The /select handler is used to perform search queries while the /suggest handler is used to get suggestions for autocomplete.

If you wonder how to format your queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

Note that we also provide {DATAFARI_BASE_URL}/rest/v2.0/search/noaggregator that does exactly the same thing as the search API, except that there is no aggregation on it to avoid infinite loops when using the aggregator mode.

For Datafari Enterprise Edition only: To manage security and user ACLs in results, see this page : https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/783253542

Response format

The response format of this endpoint does not follow the standard response format of this API.

The payload of the response is the response from solr (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

For each document in the response, they have two fields for the url:

  1. doc.url : the original url of the document

  2. doc.click_url : The url to use for the href link to send the user to the document (and will track user clicks to get statistics in the search engine)

GET /rest/v2.0/results/export?*

This is the endpoint to perform an export of the result of a provided query. Here are the parameters to provide:

  • query: the main query to perform. ex:
    query=*:*

  • facetQuery: An array containing all the facet queries. ex:
    facetQuery[]={!key=From%20100KB%20To%2010MB}original_file_size:[102400 TO 10485760]&facetQuery[]={!key=More%20Than%2010MB}original_file_size:[10485760 TO *]

  • facetField: An array containing all the facet fields. ex:
    facetField[]=extension&facetField[]=language&facetField[]=source

  • fq: An array containing all the active filter queries. ex:
    fq[]={!tag=query}original_file_size:[102400 TO 10485760]&fq[]={!tag=author}(author:"agence de l'eau artois picardie")

  • sort: The sort method to apply to results, can be either "score desc", or "score asc". ex:
    sort=score desc

  • fl: The list of fields that must be returned in the results. The fields must be separated by a coma. ex:
    fl=title,last_modified,url

  • nbResults: The number of results that the export file must contain. ex:
    nbResults=500
    Be careful with this parameter, because the higher is the number, the more the query will take time and the export file will be big

  • type: The type of the export file to generate. Currently (December 2022) the only supported type is “excel”:
    type=excel

Here is an example of a GET request to the export API:

/rest/v2.0/results/export?query=*:*&facetQuery[]=original_file_size:[102400 TO 10485760]&facetQuery[]=original_file_size:[10485760 TO *]&facetField[]=extension&facetField[]=language&fq[]=original_file_size:[102400 TO 10485760]&sort=score desc&fl=title,last_modified,url&nbResults=10&type=excel

The response of this endpoint is a bytes input stream of the generated export file. In a standard web browser like chrome, it will trigger a download process

V1.0

Bellow is a set of API endpoints that are implemented or in the roadmap. Endpoints that are not implemented are clearly identified by the “NOT IMPLEMENTED” string in the response column. Those endpoints return a 501 HTTP Response code when queried (which is the code for the NOT_IMPLEMENTED http error). For implemented endpoints, query body and format for the content object of the response in case of success are provided.

The auth endpoint is particular and can't be called using AJAX, the user must be redirected to this endpoint and Datafari will redirect the user back to the callback URL once the authentication is performed successfully.

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

METHOD

URL

DESCRIPTION

QUERY BODY

RESPONSE

PROTECTED

GET

users/current

Get the information about the currently connected user

 

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current

Update user information, only the language and uiConfig can be modified.

{ "lang"?:{String} "uiConfig"?: {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Both arguments are optional, if none is provided, nothing is done

{ "name":{String}, "roles":[{Strings}], "lang": {String} "uiConfig": {Obj} }

 

Authenticated User

GET

users/current/uiconfig

Get only the uiConfig for the current user

 

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

Authenticated User

PUT

users/current/uiconfig

Update only the uiConfig for the current user

{ "uiConfig": {Obj} }

see Customizing DatafariUI for more information about the uiConfig object.

 

{ "uiConfig": {Obj} }

echos the query

Authenticated User

GET

status/features/favorites

Provide the status of the favorite feature

 

{ "activated":{boolean as String} }

 

GET

users/current/alerts

Provide the list of alerts for the current user

 

{ "alerts":[ { "_id":{String}, "core":{String}, "frequency":{String}, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String - optional}, "user": {String - username} }, ... ] }

Authenticated User

POST

users/current/alerts

Create a new alert for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String}, "filters":{String}, }

Echos the parameters with the created id

Authenticated User

PUT

users/current/alerts/{id}

Updates alert {id} for the current user

{ "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }
{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

Response should be an echo of the query with an updated ID

Authenticated User

DELETE

users/current/alerts/{id}

Delete alert {id} from the current user alerts

 

{ "_id": {String}, "core":{String - the solr core for the query}, "frequency":{String - }, "mail":{String}, "subject":{String}, "keyword":{String - optional, query keywords, defaults to *:*}, "filters":{String - optional, for facets etc., defaults to null}, }

The deleted alert object is returned.

Authenticated User

GET

users/current/savedsearches

Retrieve the set of saved searches for the current user

 

{ "savedsearches":[ { "name":{String}, "search":{String}, }, ... ] }

 

POST

users/current/savedsearches

Creates a new saved search for the current user

{ "name":{String - the name}, "search":{String - the query}, }
{ "name":{String - the name}, "search":{String - the query}, }

Echos the parameters

 

PUT

users/current/savedsearches/{savedSearchname}

Updates the saved search with name savedSearchname for the current user

{ "name":{String - the name}, "search":{String - the query}, }

The name property of the object must be the same as the name provided in the URL

{ "name":{String - the name}, "search":{String - the query}, }

Echos the saved data

 

DELETE

users/current/savedseaches/{savedSearchname}

Delete the saved search with name savedSearchname for the current user.

 

{ "name":{String - the name}, "search":{String - the query}, }

Echos the deleted saved search data

 

GET

users/current/favorites

Retrieve the list of favorites for the current user

 

{ "favorites":[ { "id": {String}, "title": {String} }, ... ] }

 

POST

users/current/favorites

Adds a new favorite for the current user

{ "id":{String}, "title":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the saved favorite

 

DELETE

users/current/favorites

Delete the favorite with the id provided in the body for the current user.

{ "id":{String} }
{ "id":{String}, "title":{String} }

Echos the information of the deleted favorite

 

GET

users/current/history

Retrieve the current user history (past queries).

 

{ "history":[str...], }

History is an array of String representing the last queries from the current user. User must be authenticated to have an history, will return an error if not authenticated.

Queries are sorted from the latest to the oldest.

Strings represent only what has been entered in the search bar (or as the q= parameter of the query to the backend)

As of commit f7be3cd03f2fe2b920af234a9bbbe3f238d35f9f

 

GET

goldenqueries

Retrieve the list of saved golden queries

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

goldenqueries/{id}

Retrieve the information of a particular golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

POST

goldenqueries

Creates a new golden query

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

PUT

goldenqueries/{id}

Updates the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

DELETE

goldenqueries/{id}

Deletes the golden query with the provided id

 

NOT IMPLEMENTED

SearchExpert
SearchAdmin

GET

fields/info

Get the list of information about solr fields that can be used.

 

{ "fields":[ {"indexed":true,"stored":false,"name":"artifact_assignees_search","type":"text_general","multiValued":true}, ... ] }

 

GET

fields/exact

Get the list of exact search fields (for advanced search)

 

{ "exactFieldsList":[ {}, ... ] }

 

GET

fields/autocomplete

Get the list of fields for which an autocomplete is available (for advanced search)

 

{ autocompleteFields:{ "solr_field_name":"suggester", ... }

 

GET

fields/label

Get the list of mappings between fields name and labels (for display purposes)

 

{ mappingFieldNameValues:{ "solr_field_name":"label", ... }

 

GET

fields/fixedvalues

Get the list of fields that can only take fixed values and their list of possible values (for advanced search)

 

{ "exactFieldsList":{ "fieldname":[{"value":"solr_field_value","label":"label_todisplay"}, "*", ...], ... } }

When an entry in the array is not an object with a value and label key but only a string, it is used both as the value and label

 

GET

help/{locale}

Get the help text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlHelpContent":{html} }

 

GET

privacy/{locale}

Get the privacy text in the provided locale with a fallback to a default text if the required locale is not available.

 

{ "htmlPrivacyContent":{html} }

 

GET

licence

Get information about the licence currently in use. To display warning message when relevant.

 

{ "type":{String}, "contact": {String - email}, "time": {String - valid | ending | overdue | expired}, "files": {String - valid | ending | overdue | expired}, "users": {String - valid | ending | overdue | expired} }

Users information is shown to administrator users only

ending = close to reach the limit of the licence
overdue = licence limit has been reached but the system still function for a limited time
expired = the system or at least part of it has stopped until a proper licence is issued

 

GET

aggregator

Get the list of sources available in the aggregator when it is active.

 

{ "aggregatorList": [ { "label": str, ?selected: bool } ] }

An array of available aggregated sources for the current user, each element of the array is an object with the following properties:

  • label: used for display and for addition to the query when one wants to query specific sources. If no list of source is added to the query and the aggregator is active, the default list of sources for the user will be used.

  • selected: optional, usually only present if set to true. Tells which sources are part of the default set of search sources for the current user.

Returns and empty array if the aggregator feature is not active.

 

GET

sources/external

Get the list of external source available

 

NOT IMPLEMENTED

 

GET

URL?url=blablabla

Redirects to the required document, used to send the user to the source document when he clicks on the result.

 

NOT IMPLEMENTED

 

GET

search/{handler}?{query}

Perform a search or suggest query.

 

SPECIFIC RESPONSE FORMAT

 

GET

results/export

Get the csv version of the results for export

 

NOT IMPLEMENTED

 

GET

results/download?file=path

download the provided file from the results

 

NOT IMPLEMENTED

 

GET

auth?callback=url

 

User must be redirected to this URL, Datafari will redirect to the callback URL after the auth process is complete.

User redirected to the callback URL

 

Keep in mind that for now, this API is meant to cover standard users actions only. Admin actions are out of the scope for the time being.

Details

Special cases

Auth

For use authentication, the browser must be redirected to the auth endpoint. Once Datafari has finished the authentication process, the user is redirected to the callback URL provided as a URL parameter.

The URL to redirect the user to is:

{DATAFARI_BASE_URL}/rest/v1.0/auth?callback=url

Provide any URL you need the user to be send back to as the value for the callback parameter.

GET /rest/v1.0/search/*

This is the endpoint to perform a search request. This endpoint expects a search handler to be provided as well as all the elements of a solr query as URL parameters. A simple example for a search query would be:

GET {DATAFARI_BASE_URL}/rest/v1.0/search/select?q=*:*

This endpoints allows the use of only a few selected search handlers for security reasons. The handlers that can be called are different depending on the value of the special “action” URL parameter.

action=

handlers allowed

action=

handlers allowed

search

OR

unset

/select

/stats

/statsQuery

/

suggest

/suggest

Configuration specific handlers for advanced autocomplete functionalities (entity recognition, …)

The main handlers to keep in mind are /select and /suggest.

The /select handlers is used to perform search queries while the suggest handler is used to get suggestions for autocomplete.

For how to format you queries (either for search or query), please refer to the Solr documentation as well as the rest of Datafari’s documentation for the fields available.

Response format

The response format of this endpoint does not follow the standard response format of this API. The payload of the response is the response from solr unfiltered (please refer to the Solr documentation to see what those response look like or experiment with the endpoint).
If solr encountered an error, the endpoint will most of the time respond with 200 status, the error being in the solr response itself.

If an error occurred while Datafari is querying Solr, the response may be a 500 or 5xx http response with possibly no JSON (and maybe an html page as a response body).

Standard endpoints

GET /rest/v1.0/users/current

This endpoints returns the information about the currently connected user in the following form:

{ "name": {username} "roles": [{roles list}] "lang": {locale} }

Exemple request / response

Request:

curl "https://localhost/Datafari/rest/v1_0/current"

Response:

HTTP 200/OK { "status": "OK", "content": { "name": "admin" "roles": ["SearchAdmin"] "lang": "en" } }

 

Related content