Pagination, filtres et tri

L'API expose la majorité de ses ressources sous forme de listes (offres, candidatures, articles…). Pagination, filtrage et tri sont standardisés sur l'ensemble des endpoints de listing.

Pagination

• per_page : nombre d'éléments par page (défaut 10, maximum 100).
• page : numéro de page (1-indexé, défaut 1).

curl "https://api.diamondcareers.fr/diamond/v1/offres?per_page=50&page=2" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Renvoie les offres 51 à 100 de votre catalogue.

En-têtes de pagination

Chaque réponse de listing contient :

• X-Total : nombre total d'éléments correspondant aux filtres,
• X-Total-Pages : nombre total de pages disponibles,
• Link : liens vers first, prev, next, last (RFC 5988).

HTTP/1.1 200 OK
Content-Type: application/json
X-Total: 1234
X-Total-Pages: 25
Link: <https://...?page=1>; rel="first",
      <https://...?page=2>; rel="prev",
      <https://...?page=4>; rel="next",
      <https://...?page=25>; rel="last"

Bonnes pratiques

Choisissez une taille adaptée. Affichage interactif : 10–25. Synchronisation backend : 50–100.

Surveillez X-Total. En cas de synchronisation lourde, anticipez le volume avant le parcours.

Préférez la synchro par delta. Pour les ressources ordonnées dans le temps, filtrez par filter[modified_after]=YYYY-MM-DD plutôt que de paginer toute la collection.

Tri

• orderby : date, modified, title, id selon la ressource.
• order : asc ou desc. Par défaut, desc pour les ressources triées par date.

# Les 20 dernières offres modifiées en premier
curl "https://api.diamondcareers.fr/diamond/v1/offres?orderby=modified&order=desc&per_page=20" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Filtres

Recherche plein-texte

Le paramètre s cherche dans les champs principaux (titre, description selon la ressource).

curl "https://api.diamondcareers.fr/diamond/v1/offres?s=chef+pâtisserie" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Résultats triés par pertinence quand s est utilisé.

Filtres par champ

filter[<champ>]=<valeur> — filtre exact. Champs disponibles selon la ressource (voir spécification OpenAPI).

# Offres dans la ville de Paris
curl "https://api.diamondcareers.fr/diamond/v1/offres?filter[city]=Paris" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

# Candidatures sur une offre spécifique
curl "https://api.diamondcareers.fr/diamond/v1/candidatures?offer_id=4128" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Combinable :

curl "https://api.diamondcareers.fr/diamond/v1/offres?filter[city]=Paris&filter[contract_type]=cdi" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Filtre par taxonomie

curl "https://api.diamondcareers.fr/diamond/v1/offres?tax[job_category]=cuisine" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Taxonomies disponibles : job_category, contract_type, establishment_type. Voir /taxonomies/{name} pour récupérer la liste de termes.

Filtre par statut

curl "https://api.diamondcareers.fr/diamond/v1/offres?status=pending" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Inclusion par identifiants

curl "https://api.diamondcareers.fr/diamond/v1/offres?include=12,42,87,103" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Combiner pagination, tri, filtres

Tous les paramètres sont combinables :

curl "https://api.diamondcareers.fr/diamond/v1/offres?\
filter[city]=Paris&\
tax[job_category]=cuisine&\
orderby=modified&\
order=desc&\
per_page=25&\
page=1" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

Synchroniser un grand volume

1. Filtrer par date plutôt que paginer toute la collection.

curl "https://api.diamondcareers.fr/diamond/v1/offres?\
filter[modified_after]=2026-05-01T00:00:00Z&\
per_page=100" \
  -H "Authorization: Bearer $DIAMOND_TOKEN"

2. Paralléliser raisonnablement. 5 à 10 requêtes simultanées maximum (voir Rate limits).

3. Stocker un curseur de synchronisation. Mémorisez la date du dernier élément traité ; au passage suivant, demandez les éléments modifiés après cette date. Évite les sauts entre deux pages quand les données évoluent.

4. Logique idempotente. Un même élément peut revenir deux fois entre deux requêtes successives. Appliquer la même mise à jour deux fois ne doit créer ni doublon ni incohérence.

Performance

• Demandez seulement les champs nécessaires quand _fields=id,title,date est supporté.
• Mettez en cache les ressources peu changeantes (taxonomies, listes de villes, catégories) côté votre intégration.
• Évitez les boucles N+1. Utilisez include pour récupérer plusieurs ressources liées en lot.