Structurer les missions, candidatures et API sans perdre les responsabilités

2. Donner à chaque mission une identité et une provenance

L’identifiant technique d’une mission reste stable pendant ses corrections. Une version ou date de mise à jour permet au consommateur de détecter le changement. La provenance indique quelle agence ou quel système fait autorité ; elle ne doit pas être remplacée par le nom de la plateforme qui relaie l’information.

• Identifiant stable sans donnée personnelle
• Version ou date de modification
• Agence source et système d’origine
• État brouillon, publié, suspendu, clos ou expiré
• Date de début et fin de validité
• Identifiant de remplacement si une mission est republiée

3. Modéliser la fiche mission pour une décision humaine

Un schéma utile ne se limite pas à un titre et une description. Il rend explicites le travail, le temps, le lieu, les conditions, les prérequis et les informations à confirmer. Chaque champ distingue valeur connue, valeur inconnue et non-applicabilité ; une chaîne vide ne doit pas devenir une hypothèse.

4. Référentiels métiers : partager un vocabulaire, pas une décision

ESCO fournit une classification multilingue de professions, aptitudes et compétences, accessible par API et par jeux de données versionnés. Ses concepts ont des identifiants durables et peuvent compléter un vocabulaire national ou interne.

Associer une mission à un concept facilite la recherche et l’échange, mais ne prouve ni la maîtrise d’une compétence par une personne, ni son aptitude à un poste particulier. Conservez le libellé source, le référentiel, sa version, l’identifiant du concept et la méthode de correspondance.

• Référentiel et version
• URI ou code du concept
• Libellé dans la langue affichée
• Libellé original de l’agence
• Correspondance humaine, importée ou proposée
• Date de validation et possibilité de correction

5. Une candidature transporte le minimum nécessaire

La candidature référence une mission et transmet les informations professionnelles nécessaires au premier examen. Elle ne recopie pas automatiquement tout un profil, ne joint pas un document sensible par défaut et ne transforme pas une donnée facultative en critère éliminatoire.

Le guide CNIL du recrutement rappelle les principes de finalité, d’information, d’accès, de droits et de conservation. Le responsable du traitement doit être identifiable ; l’API ne doit pas masquer cette responsabilité derrière un identifiant technique.

6. Choisir le format selon l’usage

JSON convient aux échanges structurés et imbriqués ; CSV facilite certains exports tabulaires ; un référentiel lié peut utiliser des URI et des formats de données liés. Le choix du format ne dispense jamais de publier un schéma, une version, un encodage, des exemples fictifs et des règles d’erreur.

7. Décrire l’API avant de l’ouvrir

OpenAPI décrit de manière indépendante du langage les opérations, paramètres, schémas et réponses d’une API HTTP. Une description utile couvre aussi l’authentification, les erreurs, les limites de débit, la pagination, la compatibilité et les exemples sans donnée réelle.

1. Nommer les ressources et leurs états
2. Définir schémas d’entrée et de sortie
3. Documenter authentification et droits par rôle
4. Prévoir pagination et filtres bornés
5. Définir erreurs stables et corrélables
6. Publier version et politique de dépréciation
7. Tester avec des fixtures fictives sans secret

8. Rendre les écritures idempotentes et les événements rejouables

Une candidature ou un changement d’état peut être renvoyé après un timeout. Une clé d’idempotence et une contrainte d’unicité empêchent le double enregistrement. Un événement possède un identifiant, une version de schéma et la version de l’objet concerné ; le consommateur ignore un doublon et détecte un événement ancien reçu après un plus récent.

• Clé d’idempotence bornée à l’acteur et à l’opération
• Réponse identique lors d’un rejeu valide
• Ordre fondé sur la version de l’objet, pas seulement l’heure réseau
• Accusé distinct de la décision métier
• File de quarantaine pour événement invalide
• Rejeu manuel borné et audité

9. Importer sans créer deux vérités

Un connecteur versionné lit une source déclarée, reprend depuis un checkpoint, valide le schéma, déduplique et publie atomiquement. Les erreurs temporaires utilisent un retry avec backoff ; les données invalides vont en quarantaine. Un seul ordonnanceur pilote une même source et une même ressource.

L’état courant n’est remplacé qu’après validation complète du lot. Le manifeste publié indique source, version, fraîcheur et empreinte ; l’ancienne version reste disponible pour rollback. Une extension future à une nouvelle agence ou à un autre référentiel doit changer la configuration ou le connecteur, pas le cœur du modèle.

10. Sécurité, confidentialité et journalisation

Les listes publiques ne contiennent aucune candidature. Les réponses authentifiées restent en cache privé ou no-store. Les journaux techniques excluent CV, messages libres, coordonnées et jetons ; ils conservent seulement identifiants techniques, résultat, durée, code d’erreur et corrélation expurgée.

• Contrôle d’accès par rôle et agence
• Révocation et expiration des accès
• Chiffrement en transit
• Aucun secret dans URL ou bundle public
• Export et correction via le responsable identifié
• Durées de conservation documentées
• Test de non-fuite entre agences et profils

11. Checklist d’un contrat d’échange exploitable

1. Objets et responsabilités séparés
2. Identifiants, provenance et versions définis
3. Schémas et valeurs inconnues documentés
4. Référentiels nommés avec leur version
5. Données de candidature minimisées
6. Droits et authentification précisés
7. Idempotence, pagination et erreurs décrites
8. Imports à checkpoint et publication atomique
9. Caches et journaux sans donnée personnelle
10. Dépréciation, rollback et contact de correction prévus

Limite publique IntériMatch

IntériMatch ne publie aujourd’hui aucune API de missions ou de candidatures, aucun connecteur agence, aucun compte réel et aucun service d’e-mail. La démonstration fictive illustre des états locaux. Ce guide définit une méthode d’interopérabilité et ses critères de contrôle ; il ne constitue ni une documentation d’API active ni une annonce d’intégration ESCO.