> ## 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.

# Self-Discovery

> Self-discovery principle and API navigation

## Self-Discovery Principle

The JobAffinity REST API is **self-discoverable** and **self-documented**. Only the main starting URL is needed: `https://jobaffinity.fr/restapi/v1`

<Warning>
  It is **not necessary** to manually construct URLs. Relation URLs are provided in API responses. Ad-hoc URL construction is discouraged as URLs may change without a major version change.
</Warning>

## Root Resource

The root resource lists the exposed high-level services and provides the API status.

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

### Example Response

```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."
  }
}
```

## Monitoring Fields

### Version and Migration

* **`_version`**: Minor version of the API in use
* **`_last_version_url`**: Root URL of the latest available version (equals `_self` if you're already using the latest version)
* **`_expiration`**: Expiration date of the version in use (`null` if no expiration planned)

<Warning>
  **Important**: Set up an alert system on the `_expiration` field. When it becomes different from `null`, a migration will be necessary.
</Warning>

### Changelog

The **`_changelog`** field provides a link to the API evolution history.

<Tip>
  Regularly consult the changelog to discover new possibilities offered by the API.
</Tip>

## Entry Points

The other fields in the root resource (`candidates`, `jobs`, etc.) provide the main API entry points with their respective URLs.

## API Navigation

Always use the URLs provided in `_self` fields to navigate the API:

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

This approach ensures your code remains functional even if URLs change.