# Recherche

Cette collection décrit les recherches de Anakeen Platform.

# URL

L'URL d'accès est: /api/v2/searches/

# Méthodes

La collection searches implémente les éléments suivants:

  • Collection: il n'y a pas d'accès possible directement auprès de la collection.
Action URL Action effectuée
GET /api/v2/searches Liste des recherches
POST /api/v2/searches N/A
PUT /api/v2/searches N/A
DELETE /api/v2/searches N/A

N.B.

Une recherche étant un Smart Element Anakeen Platform, la création d'une nouvelle recherche passe par l'utilisation de l'entrée /api/v2/smart-structures/SEARCH/smart-elements/. De plus, il existe différents type de recherches.

  • Ressource
Action URL Action effectuée
GET /api/v2/searches/<search>/smart-elements/ Contenu de la recherche search
POST /api/v2/searches/<search>/smart-elements/ N/A
PUT /api/v2/searches/<search>/smart-elements/ N/A
DELETE /api/v2/searches/<search>/smart-elements/ N/A

# Liste des recherches

# URL canonique

GET /api/v2/searches/

Récupération de la liste des recherches accessibles.

# Contenu

Le contenu de la requête est vide.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data contient les champs suivants:

  • requestParameters contient un résumé des paramètres de la requête en cours (pagination et orderBy),
  • uri: URI d'accès à la collection,
  • documents: un tableau de recherche (sous la même forme que les Smart Elements unitaires).
    Chaque Smart Element est un objet contenant les entrées suivantes:
  • properties: liste des propriétés de la recherche,
  • uri: URI de contenu de la recherche.

Exemple:

{
  "success": true,
  "data": {
    "requestParameters": {
      "slice": 10,
      "offset": 0,
      "length": 10,
      "orderBy": "title asc, id desc"
    },
    "uri": "/api/v2/searches/",
    "documents": [
        {
        "properties": {
            "id": 1894,
            "title": "Les articles intéressants",
            "icon": "api/v1/images/assets/sizes/24x24c/search.gif",
            "initid": 1894,
            "name": null,
            "revision": 0
        },
        "uri": "/api/v1/searches/1894/documents/"
        },
        [...]
    ]
  }
}

# En cas d'échec

Les raisons d'échec spécifiques à cette requête sont:

Raison Status HTTP Code d'erreur
Sens de l'orderBy inconnu 400 CRUD0501
Smart Field ou propriété d'orderBy invalide 400 CRUD0502

# Résultat partiel

# Pagination et tri

La liste des Smart Elements peut être paginée et ordonnée.
Les mots clefs GET sont les suivants:

  • orderBy : <Smart Field|propriété>:<asc:desc>
    • indique dans quel sens la collection doit être triée,
    • valeur par défaut: title:asc.
  • slice:
    • indique le nombre maximum de Smart Elements à retourner,
    • valeur par défaut 10.
  • offset:
    • indique le nombre d'éléments à exclure avant de retourner la collection,
    • valeur par défaut: 0.

N.B.

Le paramètres appliqués sont résumés dans le retour de la collection requestParameters.

# Information retournées

Les Smart Elements peuvent être retournés avec plus ou moins d'informations.

  • GET /api/v2/searches/?fields=document.properties
  • GET /api/v2/searches/?fields=document.properties.id,document.properties.title

Par défaut: fields=document.properties

Fields Signification Remarques
document.properties Récupère l'ensemble des propriétés par défaut "id", "title", "icon", "initid", "name", "revision"
document.properties.all Récupère toutes les propriétés
document.properties.<prop> Récupère la propriété indiquée

# Cache

La collection n'a pas de cache.

# Consultation du contenu d'une recherche

# URL canonique

GET /api/v2/searches/<search>/smart-elements/

Récupération de la liste des Smart Elements trouvés par la recherche search.

# Contenu

Le contenu de la requête est vide.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data contient les champs suivants:

  • uri: URI d'accès de la collection,
  • properties: contient le titre de la recherche et son identifiant,
  • documents: un tableau de Smart Elements (sous la même forme que les Smart Elements unitaires).
    Chaque Smart Element est un objet contenant les entrées suivantes:
  • properties: liste des propriétés du Smart Element,
  • attributes: liste des Smart Fields du Smart Element (facultatif),
  • uri: URI d'accès du Smart Element.

Exemple:

{
  "success": true,
  "messages": [],
  "data": {
    "requestParameters": {
      "slice": 10,
      "offset": 0,
      "length": 1,
      "orderBy": "title asc, id desc"
    },
    "uri": "/api/v2/searches/5236/smart-elements/",
    "properties": {
      "title": "Articles intéressants",
      "initid": 94203
    },
    "documents": [
      {
        "properties": {
          "id": 26653,
          "title": "La culture des perles",
          "icon": "api/v2/images/assets/sizes/24x24c/article.png",
          "initid": 1425,
          "name": null,
          "revision": 1
        },
        "uri": "http://www.example.net/api/v2/smart-elements/1425.json"
      }
    ]
  }
}

N.B.

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

# En cas d'échec

Les raisons d'échec spécifiques à cette requête sont:

Raison Status HTTP Code d'erreur
Impossible d'exécuter la recherche 403 Forbidden CRUD0201
Sens de l'orderBy inconnu 400 CRUD0501
Smart Field ou propriété d'orderBy invalide 400 CRUD0502
Dossier non trouvé 404 ROUTES0105
L'identifiant de la recherche ne correspond pas à une recherche 404 ROUTES0126

# Résultat partiel

# Pagination et tri

La liste des Smart Elements peut être paginée et ordonnée.
Les mots clefs GET sont les suivants:

  • orderBy : <Smart Field|propriété>:<asc:desc>
    • indique dans quel sens la collection doit être triée; on peut mettre plusieurs valeurs séparées par des ,
    • valeur par défaut: title:asc.
  • slice:
    • indique le nombre maximum de Smart Elements à retourner, sa valeur est un entier ou le mot clef all,
    • valeur par défaut 10.
  • offset:
    • indique le nombre d'éléments à exclure avant de retourner la collection,
    • valeur par défaut: 0.

N.B.

Le paramètres appliqués sont résumés dans le retour de la collection requestParameters.

Exemple:

  • GET api/v2/searches/<search>/?orderBy=title:asc,id:desc&slice=100&offset=20

# Informations retournées

Les Smart Elements peuvent être retournés avec plus ou moins d'informations.

  • GET /api/v2/searches/<search>/smart-elements/?fields=document.properties
  • GET /api/v2/searches/<search>/smart-elements/?fields=document.properties.id,document.properties.title
  • GET /api/v2/searches/<search>/smart-elements/?fields=document.attributes
  • GET /api/v2/searches/<search>/smart-elements/?fields=document.attributes.my_smartField

Par défaut : fields=document.properties

Fields Signification Remarques
document.properties Récupère l'ensemble des propriétés par défaut "id", "title", "icon", "initid", "name", "revision"
document.properties.all Récupère toutes les propriétés
document.properties.<prop> Récupère la propriété indiquée
document.attributes Ajoute tous les Smart Fields de la Smart Structure référencée par la recherche S'il n'y a pas de Smart Structure référence, alors aucun Smart Field n'est retourné
document.attributes.my_smartField Ajoute le Smart Field my_smartField Si le Smart Field n'existe pas dans un des Smart Elements, il est retourné vide

# Cache

La collection n'a pas de cache.