Skip to main content

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

​
Root Resource

The root resource lists the exposed high-level services and provides the API status. 
GET /restapi/v1

​
Example Response

{
  "_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)
Important: Set up an alert system on the _expiration field. When it becomes different from null, a migration will be necessary.

​
Changelog

The _changelog field provides a link to the API evolution history.
Regularly consult the changelog to discover new possibilities offered by the API.

​
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: 
{
  "job": {
    "_self": "/restapi/v1/job/42",
    "applications": {
      "_self": "/restapi/v1/job/42/application"
    }
  }
}
This approach ensures your code remains functional even if URLs change.