Commit 97215789 authored by sim's avatar sim


parent 18afb6e4
# Gargantext Light REST-API
There are two REST endpoints for the time being. First the Python backend which
takes care of authentication by delivering JSON Web Tokens, and which will
expose routes to create text corpora, handle ngram lists, build graphs, etc.
Secondly PostgREST, wich exposes database views through its own REST interface.
Those views always provide a read access to gargantext data, and sometimes
a write access. Permissions are handled at database-level, when a user
has no read rights for specific nodes, they are just not returned, they are
"invisible" to this user. When attempting to write on unauthorized nodes, an
error should be returned.
For the development phase those two endpoints are accessible through
<> and
## Python Django backend
Prefix on dev: `/light/`
For example: <>
### Authentication
#### Get a JSON Web Token
See <>.
### ...
[Work in progress]
## PostgREST backend
Current version: 4.4
Prefix on dev: `/postgrest/`
For example: <>
General documentation to query PostgREST endpoint:
HTTP status codes returned by PostgREST:
Database is not exposed directly, data is accessible through dedicated views
located in a separated PostgreSQL schema.
### Nodes
View name: `nodes`
Nodes are the main entities to represent data in gargantext. Each node have a
parent, except USER nodes. Node can also be related between them by a
many-to-many relationship, and can be related to ngrams in three different ways
(to be detailed later).
This view provides a read and write access. When inserting new nodes (`POST`
verb) some fields are mandatory and some others have default values. See
[below](#nodes-view-schema) for more details. Please remember that database
will not automagically enforce all conventions and constraints of the
gargantext data model, such as node relationships (ie. a PROJECT node must
be the child of a USER node, a CORPUS node must be the child a PROJECT node,
#### Types
For the moment there are 18 types of nodes, some are subject to changes,
here are the 4 main types which are not likely to change anytime soon.
| Type id | Type name |
| -------: | :-------- |
| 1 | USER |
| 2 | PROJECT |
| 3 | CORPUS |
| 4 | DOCUMENT |
#### Nodes view schema
When querying the nodes view (or related views such as documents), each node
is represented as a JSON object with these fields:
| Field | JSON type | Required at insertion | Description |
| -------------: | :------------------- | :--------------------- | :--------------------------------------------------------------------------- |
| id | int | Automatic* | Unique id of this node |
| type | int | Yes | [Type id](#types) of this node |
| user_id | int | Default = current user | Owner id of this node (an internal id, **not** the id of its USER node) |
| parent_id | int | Yes | Node id of this node's parent |
| name | string | Default = empty string | Label of this node, can be used for different purposes depending on its type |
| created | datetime as a string | Default = now | Creation date of this node |
| data | object | Default = {} | [Hyperdata](#hyperdata) of this node |
| title_abstract | string | Automatic* | Only meaningful for DOCUMENT nodes: full-text index on title + abstract |
\* Please don't provide any value, database will generate one automatically.
#### Hyperdata
Type specific data of each node is stored in the `data` field, as a JSON
object. For example documents abstract and title are stored here. There is no
strict schema, a documentation for each type and field remains to be written.
Here is an excerpt of a document `data` field:
"id": "RePEc:taf:quantf:v:2:y:2002:i:1:p:24-30",
"url": "",
"type": "article",
"title": "Variance reduction for Monte Carlo simulation in a stochastic volatility environment",
"source": "Quantitative Finance",
"authors": "Jean-Pierre Fouque, Tracey Andrew Tullie",
"abstract": "We propose a variance reduction method for Monte Carlo computation of option prices in the context of stochastic volatility. This method is based on importance sampling using an approximation of the option price obtained by a fast mean-reversion expansion introduced in Fouque et al (2000 Derivatives in Financial Markets with Stochastic Volatility (Cambridge: Cambridge University Press)). We compare this with the small noise expansion method proposed in Fournie et al (1997 Asymptotic Anal. 14 361-76) and demonstrate numerically the efficiency of our method, in particular in the presence of a skew.",
"publication_date": "2017-12-22 12:45:10+00:00",
#### Fetch USER node of `User(id=<user_id>)`
#### Fetch all main nodes belonging to `User(id=<user_id>)`
### Documents
View name: `documents`
DOCUMENT [nodes](#nodes-view-schema) with an additional field `ngram_count`
which is the number of ngrams of the document selected in its corpus MAPLIST
("Map terms" in the "Terms" tab of legacy gargantext).
This view is read-only.
#### Fetch documents from `CorpusNode(id=<corpus_id>)`
#### Search for `<query>` in documents from `CorpusNode(id=<corpus_id>)`
NOTICE: before postgrest 4.4 use `english.fts` instead of `fts(english)`.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment