API documentation

Preamble

This paper aims to describe the use of the API allowing third-party applications with interact with the wagapi platform for storage, classification, access and sharing of data.

Requirements

Using the API requires a key for access to the API, which will be called api_key or simply key in the following lines. You can generate your unique key through the settings panel of your wagapi account (accessible from the top of this page). To access a specific account, user name and password of the account are also required for the application to authenticate.

General concepts

Authentication

Authentication is based on the use of an authentication token, the user identifier, in this case its API identifier (or API key) and the account ID being accessed. The call /access/account detailed below is a simple method that allows a third-party application to access an account based on the username and password of the account. If successful, the method a token and the account ID. Token and the API username must then be systematically inserted into the subsequent calls:

either in the headers, respectively associated with the header "auth_token" and "key"

either in GET or POST variables, depending on the method used, respectively associated with the variables "auth_token" and "key"

The account ID is automatically inserted into the URI. Its place is specified in the detailed description of the calls in the account_id variable.

Call

The nature of the call is contained in the url. Parameters are passed in the variable data, regardless of the method used, which has the following form:

		{
			input1: {}, [] or string of input variables (depending on the call)
			input2: {}, [] or string of input variables (depending on the call)
			input3: {}, [] or string of input variables (depending on the call)
			....
		}
		

The content of data is actually an associative array, whose indices are strings. According to the programming language, it is an array or an object. In the following, the parameters will refer to data fields. Before being passed as a parameter via POST or GET variable data are to be encoded in JSON format. It may be necessary, for example to use JSON.stringify () in javascript or json_encode () in PHP.

Answers

If successful, the response http calls will be systematically of type 200 and in json format. It must therefore be decoded. It will be structured, after decoding, as follows:

		{
			output1: {}, [] or string of input variables (depending on the call),
			output2: {}, [] or string of input variables (depending on the call)
			....
		}
		

In case of failure, the answer will be typically of type 400-404, and an error message will be included in the response body.

Referencing documents

Each document of a user account is identified by a unique identifier. Calls that target documents must necessarily reference the identifiers of one or more documents. These identifiers are passed as an array of values, usually stored in a variable named index.

			var index = [id_doc_1, id_doc_2 ...] / / javascript
			$index = array (id_doc_1, id_doc2, ...) / / php
		

Tags and paths

Data classification in Wagapi is not based on the use of a hierarchical tree but relies on the characterization by keywords or tags. Whenever it comes to the path,, it is in fact a list of keywords that could be likened to a series of subdirectories. For instance:

path: [tags1, tags2, tags3]

corresponds to a location together the three key words which a tree is equivalent to the classical path /tag1/tag2/tag3/, with the difference that the order of the tags does not matter. And locations are equivalent, which provides great flexibility in the classification of the information.

[Tags1, tags2, tags3] <=> [tags1, tags3, tags2] <=> [tags3, tags2, tags1] <=> ...

The name under which a document is saved (without extension) is itself a tag.

Character Encoding

All strings sent to the server must be encoded in UTF8.