> ## Documentation Index
> Fetch the complete documentation index at: https://api.jobaffinity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-découverte

> Principe d'auto-découverte et de navigation dans l'API

## Principe d'auto-découverte

L'API REST JobAffinity est **auto-découvrable** et **auto-documentée**. Seule l'URL principale de départ est nécessaire : `https://jobaffinity.fr/restapi/v1`

<Warning>
  Il n'est **pas nécessaire** de construire des URLs manuellement. Les URLs de relation sont fournies dans les réponses de l'API. La construction ad-hoc d'URL est déconseillée car les URLs peuvent être modifiées sans changement majeur de version.
</Warning>

## Ressource racine

La ressource racine liste les services de haut niveau exposés et donne l'état de l'API.

```bash theme={null}
GET /restapi/v1
```

### Exemple de réponse

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1",
  "_version": "1.10",
  "_last_version_url": "/restapi/v1",
  "_expiration": null,
  "_changelog": {
    "_self": "/restapi/changelog"
  },
  "candidates": {
    "_self": "/restapi/v1/candidate",
    "description": "List of visible candidates"
  },
  "jobs": {
    "_self": "/restapi/v1/job",
    "description": "List of visible jobs."
  }
}
```

## Champs de surveillance

### Version et migration

* **`_version`** : Version mineure de l'API utilisée
* **`_last_version_url`** : URL racine de la dernière version disponible (vaut `_self` si vous utilisez déjà la dernière version)
* **`_expiration`** : Date d'expiration de la version utilisée (`null` si aucune expiration prévue)

<Warning>
  **Important** : Mettez en place un système d'alerte sur le champ `_expiration`. Lorsqu'il devient différent de `null`, une migration sera nécessaire.
</Warning>

### Changelog

Le champ **`_changelog`** fournit un lien vers la liste des évolutions de l'API.

<Tip>
  Consultez régulièrement le changelog pour découvrir les nouvelles possibilités offertes par l'API.
</Tip>

## Points d'entrée

Les autres champs de la ressource racine (`candidates`, `jobs`, etc.) fournissent les points d'entrée principaux de l'API avec leurs URLs respectives.

## Navigation dans l'API

Utilisez toujours les URLs fournies dans les champs `_self` pour naviguer dans l'API :

```json theme={null}
{
  "job": {
    "_self": "/restapi/v1/job/42",
    "applications": {
      "_self": "/restapi/v1/job/42/application"
    }
  }
}
```

Cette approche garantit que votre code reste fonctionnel même si les URLs changent.