Aller au contenu principal

API basics

Interroger une collection de ressources​

La plupart des endpoints de collection (GET /v1/<resource_type>) supportent les paramètres de requête filters, sort, fields et la pagination via skip & limit. Nous répondons toujours en JSON (Content-Type: application/json).

Exemples (Contact)
https://rest.leadfox.co/v1/contact?filters=email = [email protected]
https://rest.leadfox.co/v1/contact?sort=email
https://rest.leadfox.co/v1/contact?fields=_id,email
https://rest.leadfox.co/v1/contact?skip=0&limit=10
attention

Assurez-vous que vos URLs sont toujours correctement encodées ; par simplicité et lisibilité, elles ne le sont pas dans les exemples :

filters=properties.firstname = John|john,properties.lastname = Doe|doe
                            ^ ^                             ^ ^
filters=properties.firstname%20=%20John|john,properties.lastname%20=%20Doe|doe
                            ^^^ ^^^                             ^^^ ^^^

Règles générales du schéma​

  • Les IDs sont des chaînes hexadécimales comme abcdef123456789000000000 (ObjectIds MongoDB).
  • Les ressources ont
    • un attribut _id, identifiant unique de la ressource.
    • un attribut _owner, identifiant unique du Client propriétaire de la ressource.
  • La plupart des dates (datetimes) sont au format ISO 8601 comme 2025-01-01T00:00:00.000Z.
    • Toujours converties et stockées en UTC.
    • Dans de rares cas, nous pouvons utiliser un timestamp en millisecondes.

Syntaxe des filtres​

Utilisez une virgule , entre les conditions pour un AND.
Utilisez une barre verticale | entre les valeurs pour un OR.
Utilisez un point . pour accéder aux attributs d'un objet imbriqué comme properties.firstname.
Utilisez un point . pour accéder aux attributs d'un objet imbriqué dans un tableau comme lists.list.
Les opérateurs sont sensibles à la casse : a = John et a = john ne retournent pas les mêmes ressources.

Opérateurs de condition
attribute = <value>
attribute != <value>
attribute > <value>
attribute >= <value>
attribute < <value>
attribute <= <value>
attribute exists <true|false>
Exemples (Contact)
filters=properties.firstname = John|john,properties.lastname = Doe|doe
                  ^                                ^
[
    { "properties": { "firstname": "John", "lastname": "Doe" } },
    // ...
]

À faire et à ne pas faire​

À FAIREÀ NE PAS FAIRE
Vous DEVEZ mettre un espace de chaque côté de l'opérateura = <value>a=<value>
N'utilisez la barre verticale | (OR) qu'entre des valeursa = <value>|<value>a = <value>,<value>
N'utilisez la virgule , (AND) qu'entre des conditionsa = <value>,b = <value>a = <value>|b = <value>
Vous NE DEVEZ PAS mettre d'espace autour d'une barre verticale | ou d'une virgule ,a = <value>|<value>
a = <value>,b = <value>		a = <value> | <value>
a = <value> , b = <value>
Référencer un attribut à droite de l'opérateur ne fonctionne pas, seules les valeurs statiques sont permisesobj.a = <value>obj.a = obj.b
Référencer un attribut plusieurs fois ne fonctionne pas, une seule condition par attribut est permise (la dernière l'emporte)obj.a >= 0,obj.a < 100
Exemples (Contact)
filters=properties.firstname = John|john,properties.lastname = Doe|doe
                  ^         ^^^    ^    ^
info

Cette syntaxe est assez limitée. Par exemple, vous ne pouvez que combiner les conditions en AND ; le OR entre conditions et les conditions avancées avec parenthèses () ne sont pas permis. C'est généralement suffisant pour les cas de base comme filtrer vos contacts par adresse email ou vos listes par nom.

attention

Attention en filtrant un tableau d'objets imbriqués, le résultat peut ne pas être celui attendu :

filters=lists.list = 67f427c5328bb26a393d64ca,lists.time >= 2025-01-01
             ^                                     ^

Retourne les ressources ayant au moins un élément qui satisfait la première condition lists.list = 67f427c5328bb26a393d64ca AND au moins un élément (potentiellement différent) qui satisfait la seconde condition lists.time >= 2025-01-01. Filtrer sur des éléments qui satisfont les deux conditions à la fois n'est pas supporté pour le moment.

Syntaxe de tri​

Utilisez des virgules , pour trier sur plusieurs fields à la fois.
Utilisez un moins - devant un field pour trier en ordre décroissant.

Exemples (Contact)
sort=email
sort=-email
sort=_id,email

Syntaxe des fields​

Comme nous utilisons du JSON avec des tableaux et des objets imbriqués, il peut être utile de ne récupérer que ce dont vous avez besoin pour réduire la taille des réponses.

Utilisez des virgules , pour ne récupérer que les fields voulus.
Utilisez un point . pour récupérer les attributs d'un objet imbriqué comme properties.firstname.
Utilisez un point . pour récupérer les attributs d'un objet imbriqué dans un tableau comme lists.list.

Exemples (Contact)
fields=email,properties.firstname,properties.lastname

[
    {
        "_id": "000000000000000000000000",
        "_owner": "000000000000000000000000",
        "email": "...",
        "properties": {
            "firstname": "...",
            "lastname": "..."
        }
    },
    // ...
]
info

_id & _owner sont toujours retournés, même sans être demandés.

Il n'existe pas de syntaxe pour demander les fields par défaut en y ajoutant ou en en retirant un sous-ensemble ; pour y arriver, vous devez envoyer la liste complète manuellement.

Syntaxe de pagination​

Utilisez skip & limit pour parcourir de grands ensembles de résultats.

Exemples (Contact)
skip=0&limit=10
skip=10&limit=10
skip=20&limit=10
...
info

Le limit par défaut est actuellement 100 mais pourrait changer.

PUT, pas PATCH​

Nous ne supportons pas la méthode PATCH ; notre PUT se comporte simplement comme un PATCH. Lors de la mise à jour d'une entité, vous pouvez donc envoyer des données partielles et seuls les fields fournis seront mis à jour.

Attention en mettant à jour un objet imbriqué dans une entité. Par défaut, l'objet imbriqué complet est remplacé. Pour ne mettre à jour qu'un sous-ensemble de ses attributs, utilisez la notation par point . pour cibler l'attribut voulu.

PUT /v1/<entity_type>/<id> HTTP/1.1
Host: rest.leadfox.co
Authorization: JWT <jwt>
Content-Type: application/json

{ "foo": { "bar": "new value" } }
attention

L'objet imbriqué Contact.properties est un cas particulier : l'objet complet est fusionné plutôt que remplacé. La notation par point n'est pas supportée pour celui-ci.