Skip to content
Snippets Groups Projects
Select Git revision
  • next_version protected
  • doc_poo
  • master default protected
3 results
Blame Permalink
web_services.md 20.83 KiB

Services web

1. Définition

Les web services sont la partie back-end de l'application ; ils se composent de plusieurs ressources qui permettent au client d'interroger la base de données, de lire/modifier des fichiers et d'effectuer des opérations sur la machine physique du serveur.

Dans vMap et autres produits Veremes, ils sont mis en place par une API-REST, ce qui signifie que l'on accède aux données selon des règles bien spécifiques.

Exemple de requête permettant de lister les cartes vMap :

https://corbieres/vmap_rest/vmap/maps

Exemple de requête permettant de voir les informations de la carte ayant pour identifiant '15' :

https://corbieres/vmap_rest/vmap/maps/{15}

L''API-REST retourne au client un résultat JSON ou XML contenant les informations demandées :

{
  "maps": [
    {
      "theme_name": "Thème Géobretagne",
      "theme_description": "Cartes Géobretagne avec fond OSM",
      "crs_name": "[EPSG:2154]-RGF93.Lambert-93",
      "map_id": 15,
      "crs_id": "EPSG:2154",
      "name": "Carte OSM Géobretagne",
      "description": "Carte Geobretagne avec un fond osm",
      "extent": "140807|6725441|303007|6799494",
      "catalog_index": 3,
      "thumbnail": "https://corbieres/vmap_ws_data/vitis/vmap_admin_map_vmap_admin_map/documents/15/thumbnail/geobret.png?d=1499068782",
      "maptheme_id": 1,
      "groups": "",
      "groups_label": ""
    }
  ],
  "status": 1
}

2. Utilisation

2.1. En-têtes

Il y a divers en-têtes essentiels à l'utilisation des ressources.

2.1.1. Accept

Valeurs possibles :
  • application/json
  • application/xml
  • application/x-vm-json
Définition

L'en-tête détermine le format de réponse demandé par le client. Les formats application/json et application/xml retournent un objet possédant un tableau qui porte le nom de la ressource (dans l'exemple ci-dessus, il s'agit de "maps"). Le format application/x-vm-json diffère en donnant comme nom du tableau "data", permettant de faire des requêtes génériques par le client.

2.1.2. Token

Le token de connexion identifie l'utilisateur de l'application, c'est grâce à lui que la ressource identifie si le demandeur possède les droits suffisants pour avoir un résultat, et c'est par son intermédiaire que se font les connexions à la base de données.

Pour des raisons de sécurité, il est strictement interdit de passer le token en tant que paramètre dans l'URL. Il faut donc le passer en en-tête
si une personne malveillante a accès au réseau (man in the middle), elle pourrait alors voir ce token et donc usurper l'identité d'un autre utilisateur.

2.1.3. X-HTTP-Method-Override

Lorsque l'on utilise régulièrement l'API-REST, il est possible que l'on soit confronté à des problèmes de longueur d'URL : à partir d'un certain nombre de caractères, les navigateurs refusent d’exécuter la requête et affichent l'erreur suivante :

414 URI Too Long

Pour pallier à cette contrainte, un en-tête X-HTTP-Method-Override a été mis en place pour envoyer une requête de type POST avec des paramètres figurant dans le body (sans limite de taille) et interprétables comme des requêtes GET :

General
    Request Method:POST

Request Headers
    X-HTTP-Method-Override: GET

2.2. Paramètres génériques

2.2.1. order_by

Permet de définir l'ordre d'affichage lorsqu'il y a plusieurs données. Par défaut, il vaut l'identifiant de la ressource.

2.2.2. sort_order

Couplé au paramètre "order_by", il permet de définir l'ordre avec les valeurs suivantes :

  • asc : ordre ascendant
  • desc : ordre descendant

2.2.3. limit

Si le paramètre "limit" est fourni, alors le tableau retourné se limite à "n" éléments.

2.2.4. offset

Souvent couplé avec les paramètres "limit" et "order_by", il peut permettre, par exemple, d'effectuer une pagination sur une liste.

2.2.5. attributs

Définit les attributs qui seront retournés par le client. Pour les renseigner, il faut écrire ces attributs en les séparant par le caractère "|".

2.2.6. distinct

True/false permet de distinguer les valeurs résultantes.

2.2.7. filter

Donne la possibilité à l’utilisateur de filtrer les données. Il faut écrire un objet JSON composé de relations et d'opérateurs.

2.2.7.1. Relations

Les relations définissent le type de condition à utiliser selon la structure JSON suivante :

{
    "relation": "AND",
    "operators":[{
        "..."
    }, {
        "..."
    }]
}

Dans cet exemple, on demande d'ajouter les filtres définis par les opérateurs selon la relation "AND". On peut également utiliser une relation "OR".

Il est aussi possible de faire dans une même requête du "AND" et du "OR" en incorporant une relation comme si c'était un opérateur :

{
    "relation": "AND",
    "operators":[{
        "..."
    }, {
        "relation": "OR",
        "operators": [{
            "..."
        }, {
            "..."
        }]
    }]
}

Ainsi, on obtient une requête constituée de "AND" et de "OR" (voir l'exemple ci-après).

2.2.7.2. Opérateurs

Plus simples à comprendre, les opérateurs se composent de trois ou quatre arguments :

  • column : nom de la colonne sur laquelle appliquer le filtre.
  • value : valeur du filtre.
  • compare_operator : type de comparaison ("=", "!=", "<>", ">=", "<=", ">", "<", "IN", "NOT IN", "IS NULL", "IS NOT NULL", "LIKE", "INTERSECT").
  • compare_operator_options (optionnel) : ajoute des options suivant le type de compare_operator.

La structure est la suivante :

{
    "column": "...",
    "compare_operator": "...",
    "value": "...",
    "compare_operator_options": {
        "..." : "..."
    }
}
2.2.7.3. Exemples

Pour être plus parlant, voici quelques exemples avec leur équivalent sous forme SQL.

En utilisant une relation AND, on peut filtrer sur plusieurs opérateurs :

{
    "relation": "AND",
    "operators":[{
        "column": "auteur",
        "compare_operator": "=",
        "value": "Laurent"
    }, {
        "column": "allume",
        "compare_operator": "=",
        "value": "true"
    }, {
        "column": "route_id",
        "compare_operator": "=",
        "value": 10
    }]
}

Équivalent SQL

auteur='laurent' AND allume='true' AND route_id=10

Si un seul opérateur est utilisé, alors il n'est pas nécessaire de renseigner de relation :

{
    "column":"auteur",
    "compare_operator":"=",
    "value":"laurent"
}

Équivalent SQL

auteur='laurent'

En utilisant des relations imbriquées, on peut effectuer des filtres complexes :

{
    "relation": "AND",
    "operators":[{
        "column":"auteur",
        "compare_operator":"=",
        "value":"laurent"
    }, {
        "relation": "OR",
        "operators": [{
            "column":"allume",
            "compare_operator":"=",
            "value":"true"
        }, {
            "column":"route_id",
            "compare_operator":"=",
            "value":10
        }]
    }]
}

Équivalent SQL

auteur='laurent' AND (allume='true' OR route_id=10)

On peut utiliser "compare_operator" = "IN" en utilisant des valeurs situées dans un tableau :

{
    "relation": "AND",
    "operators":[{
        "column":"auteur",
        "compare_operator":"=",
        "value":"laurent"
    }, {
        "relation": "OR",
        "operators": [{
            "column":"allume",
            "compare_operator":"=",
            "value":"true"
        }, {
            "column":"route_id",
            "compare_operator":"IN",
            "value":[5,10]
        }]
    }]
}

Équivalent SQL

auteur='laurent' AND (allume='true' OR route_id IN (5, 10))

Il est possible d'utiliser "compare_operator" = "LIKE" avec des valeurs suivies ou précédées du caractère "%" :

{
    "column":"auteur",
    "compare_operator":"LIKE",
    "value":"laur%"
}

Équivalent SQL