Commit d3110367 by Nicolas Joyard

Passage doc api en markdown + doc filtres

parent f1f7ca08
......@@ -3,6 +3,7 @@
import os
from flask import Flask
from flaskext.markdown import Markdown
def setup_app(name):
......@@ -30,4 +31,7 @@ def setup_app(name):
from .routes import setup_routes
setup_routes(app, { 'an': an_rest_api }, graphql_api)
# Enable Markdown
Markdown(app)
return app
......@@ -52,43 +52,9 @@
<b>API REST</b>
</header>
<article class="panel-body">
<p>L'API REST donne accès en lecture seule aux données au format JSON.</p>
<p>Les points d'entrée vers les listes d'objets sont décrits ci-dessous. Les objets JSON renvoyés par l'API comprennent des hyperliens vers d'autres sections de l'API. En particulier, les items de liste comportent toujours un lien vers une version plus détaillée et les versions détaillées comportent la plupart du temps des liens vers les entités liées.</p>
<h5>Recherche <i>full-text</i></h5>
<p>Il est possible de filtrer les résultats par une recherche textuelle, par exemple <a href="/rest/an/organes/?search=commission des lois"><code>/rest/an/organes/?search=commission des lois</code></a>. La recherche textuelle porte sur tous les champs textuels présents dans les entités.</p>
<p>Par défaut les résultats incluent les éléments comportant tous les termes recherchés mais il est possible d'écrire les requêtes différemment :
<ul>
<li>
<a href="/rest/an/organes/?search=commission or lois"><code>commission or lois</code></a> recherche les éléments comportant soit <code>commission</code>, soit <code>lois</code>.
</li>
<li>
<a href="/rest/an/organes/?search=commission -lois"><code>commission -lois</code></a> recherche les éléments comportant <code>commission</code> mais pas <code>lois</code>.
</li>
<li>
<a href="/rest/an/organes/?search=(commission or lois) -énergie"><code>(commission or lois) -énergie</code></a> recherche les éléments comportant <code>commission</code> ou <code>lois</code> mais pas <code>énergie</code>.
</li>
</ul>
</p>
<h5>Pagination</h5>
<p>Les listes d'objets sont paginées à raison de 10 objets par page, par défaut. Chaque page indique le nombre total d'objets de la collection et des liens vers les pages précédentes et suivantes, le cas échéant.</p>
<p>La taille des pages peut être modifiée (ex: <a href="/rest/an/acteurs/?page_size=20"><code>/rest/an/acteurs/?page_size=20</code></a>).</p>
<h5>Relations et personnalisation des détails</h5>
<p>Dans la version détaillée d'une entité, des liens permettent d'accéder à une version de l'entité dans laquelle les entités liées sont incluses.</p>
<p>Par exemple, le &laquo; projet de loi pour une République Numérique &raquo; (<a href="/rest/an/dossiers/DLR5L14N34516"><code>/rest/an/dossiers/DLR5L14N34516</code></a>) comporte un lien vers les acteurs à l'origine de ce projet de loi (<a href="/rest/an/dossiers/DLR5L14N34516/acteurs"><code>/rest/an/dossiers/DLR5L14N34516/acteurs</code></a>).</p>
<p>La dernière partie de cette URL constitue en réalité une indication des informations souhaitées sur le dossier <code>DLR5L14N34516</code>, en l'occurrence le champ <code>acteurs</code>. Il est possible de la personnaliser en indiquant plusieurs champs séparés par des virgules&nbsp;; par exemple <a href="/rest/an/dossiers/DLR5L14N34516/acteurs,titre,senat_chemin"><code>/rest/an/dossiers/DLR5L14N34516/acteurs,titre,senat_chemin</code></a> inclut aussi le titre du dossier et un lien vers le site du Sénat.</p>
<p>Lorsqu'un champ de relation est utilisé, il est aussi possible de préciser des chemins à inclure, en séparant les parties de chaque chemin avec des points. Par exemple, <a href="/rest/an/dossiers/DLR5L14N34516/acteurs.acteur.nom,acteurs.acteur.prenom,titre,senat_chemin"><code>/rest/an/dossiers/DLR5L14N34516/acteurs.acteur.nom,acteurs.acteur.prenom,titre,senat_chemin</code></a> aura le même résultat que le lien précédent, mais inclura en plus le nom et le prénom de chaque acteur.</p>
{% filter markdown %}
{% include "rest_api_doc.html" %}
{% endfilter %}
</article>
<table class="table table-striped table-responsive">
<tr>
......
L'API REST donne accès en lecture seule aux données au format JSON.
Les points d'entrée vers les listes d'objets sont décrits ci-dessous. Les objets JSON renvoyés par l'API comprennent des hyperliens vers d'autres sections de l'API. En particulier, les items de liste comportent toujours un lien vers une version plus détaillée et les versions détaillées comportent la plupart du temps des liens vers les entités liées.
##### Filtrage
Les résultats peuvent être filtrés par une recherche multicritère en utilisant n'importe lequel des champs des entités, par exemple [`/rest/an/acteurs/?prenom=Jean&pays_naissance=France`](/rest/an/acteurs/?prenom=Jean&pays_naissance=France). Lorsque plusieurs critères sont présents ils sont combinés avec un ET logique.
Suivant les champs utilisés, différents types de valeurs sont requis :
* Pour les champs de type texte, n'importe quelle chaine de caractère peut être utilisée
* Pour les champs numériques, seuls des chiffres peuvent être utilisés
* Pour les champs de type date, la date doit être au format `AAAA-MM-JJ`
* Pour les champs de type booléen, les valeurs `true`, `yes`, `1` sont considérées comme vraies, toutes les autres comme fausses
Il est possible de spécifier un opérateur de comparaison sous la forme `champ__operateur=valeur`. Les opérateurs suivants sont disponibles :
* `eq` : égal (comme l'absence d'opérateur)
* `ne` : différent
* `gt`, `gte`: supérieur, supérieur ou égal
* `lt`, `lte`: inférieur, inférieur ou égal
* `isnull`: permet de filtrer les valeurs vierges. La valeur associée doit être un booléen.
La requête suivante permet par exemple de lister les acteurs décédés, prénommés "Jean", et nés après le 1er janvier 1945 : [`/rest/an/acteurs/?prenom=Jean&date_deces__isnull=false&date_naissance__gt=1945-01-01`](/rest/an/acteurs/?prenom=Jean&date_deces__isnull=false&date_naissance__gt=1945-01-01)
##### Recherche *full-text*
Il est possible de filtrer les résultats par une recherche textuelle, par exemple [`/rest/an/organes/?search=commission des lois`](/rest/an/organes/?search=commission des lois). La recherche textuelle porte sur tous les champs textuels présents dans les entités.
Par défaut les résultats incluent les éléments comportant tous les termes recherchés mais il est possible d'écrire les requêtes différemment :
* [`commission or lois`](/rest/an/organes/?search=commission or lois) recherche les éléments comportant soit `commission`, soit `lois`.
* [`commission -lois`](/rest/an/organes/?search=commission -lois) recherche les éléments comportant `commission` mais pas `lois`.
* [`(commission or lois) -énergie`](/rest/an/organes/?search=(commission or lois) -énergie) recherche les éléments comportant `commission` ou `lois` mais pas `énergie`.
##### Pagination
Les listes d'objets sont paginées à raison de 10 objets par page, par défaut. Chaque page indique le nombre total d'objets de la collection et des liens vers les pages précédentes et suivantes, le cas échéant.
La taille des pages peut être modifiée (ex: [`/rest/an/acteurs/?page_size=20`](/rest/an/acteurs/?page_size=20)).
##### Relations et personnalisation des détails
Dans la version détaillée d'une entité, des liens permettent d'accéder à une version de l'entité dans laquelle les entités liées sont incluses.
Par exemple, le &laquo; projet de loi pour une République Numérique &raquo; ([`/rest/an/dossiers/DLR5L14N34516`](/rest/an/dossiers/DLR5L14N34516)) comporte un lien vers les acteurs à l'origine de ce projet de loi ([`/rest/an/dossiers/DLR5L14N34516/acteurs`](/rest/an/dossiers/DLR5L14N34516/acteurs)).
La dernière partie de cette URL constitue en réalité une indication des informations souhaitées sur le dossier `DLR5L14N34516`, en l'occurrence le champ `acteurs`. Il est possible de la personnaliser en indiquant plusieurs champs séparés par des virgules&nbsp;; par exemple [`/rest/an/dossiers/DLR5L14N34516/acteurs,titre,senat_chemin`](/rest/an/dossiers/DLR5L14N34516/acteurs,titre,senat_chemin) inclut aussi le titre du dossier et un lien vers le site du Sénat.
Lorsqu'un champ de relation est utilisé, il est aussi possible de préciser des chemins à inclure, en séparant les parties de chaque chemin avec des points. Par exemple, [`/rest/an/dossiers/DLR5L14N34516/acteurs.acteur.nom,acteurs.acteur.prenom,titre,senat_chemin`](/rest/an/dossiers/DLR5L14N34516/acteurs.acteur.nom,acteurs.acteur.prenom,titre,senat_chemin) aura le même résultat que le lien précédent, mais inclura en plus le nom et le prénom de chaque acteur.
......@@ -25,6 +25,7 @@ setup(
'eralchemy>=1.0,<2',
'flask>=0.11,<0.12',
'flask-graphql>=1.3,<2',
'flask-markdown>=0.3,<0.4',
'flask-marshmallow>=0.7,<0.8',
'flask-sqlalchemy>=2.1,<3',
'graphene_sqlalchemy>=1.0,<2',
......
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 sign in to comment