Conventions
Dates et heures
Toutes les dates utilisent ISO 8601 en UTC.
| Type | Format | Exemple |
|---|
| Date | YYYY-MM-DD | 2026-04-18 |
| Date+heure | YYYY-MM-DDTHH:mm:ssZ | 2026-04-18T14:00:00Z |
| Date+heure ms | YYYY-MM-DDTHH:mm:ss.SSSZ | 2026-04-18T14:00:00.123Z |
| Durée | ISO 8601 duration | PT30M (30 min), P7D (7 jours) |
L’heure locale Cameroun (WAT) est UTC+1. Ne jamais envoyer de date sans suffixe de fuseau.
Devises
| Code | Nom | Usage |
|---|
XAF | Franc CFA BEAC | Par défaut |
EUR | Euro | Offres internationales |
USD | Dollar US | Rare |
500000 = 500 000 XAF.
Téléphones
Format E.164 avec code pays obligatoire.
✅ +237690123456
✅ +33612345678
❌ 690123456
❌ 0690123456
Emails
Validation stricte RFC 5322. Longueur max 254 caractères.
Noms de champs
- API (JSON) :
camelCase — firstName, dateExpiration, niveauExperience
- SQL (colonnes) :
snake_case — first_name, date_expiration
- SQL (tables) :
snake_case pluriel — candidats, offres_emploi
- Enums :
UPPER_SNAKE_CASE — CDI, PENDING_APPROVAL, NEW
IDs
- Type :
long (64 bits)
- Format dans JSON : nombre entier
- Exposés tels quels (pas d’obfuscation ni de slug)
{ "id": 42, "titre": "..." }
?page=0&size=20&sort=createdAt,desc
page base 0size max 100 (clampé silencieusement)sort accepte plusieurs entrées
Tri
| Champ | Direction défaut |
|---|
createdAt | desc |
updatedAt | desc |
titre | asc |
nom | asc |
relevance | desc (recherche plein-texte) |
Langues
Les messages d’erreur et enumérations sont renvoyés selon Accept-Language (fr/en). Le français est le défaut.
Accept-Language: fr-FR,fr;q=0.9,en;q=0.8
Encodage
- Body :
UTF-8
- URL : percent-encoding standard
- Multipart : boundary généré par le client
Codes pays
ISO 3166-1 alpha-2. Cameroun = CM.
Géolocalisation
Format POINT(lon lat) pour les coordonnées PostGIS (interne). Exposé en API sous forme :
{
"latitude": 4.0511,
"longitude": 9.7679
}
Enumérations
Toujours documentées par endpoint. Liste complète : Énumérations.
Nullabilité
Champs absents omis du JSON (pas null). Exception : champs explicitement documentés comme nullable.
{
"id": 1,
"titre": "Offre",
"description": "..."
// "dateExpiration" omis si non défini
}
Casse des réponses
- Clés JSON :
camelCase strict
- Valeurs enum :
UPPER_SNAKE_CASE
- Chaînes libres : telles qu’enregistrées
Headers standards
| Header | Rôle |
|---|
Content-Type: application/json | Requête JSON |
Content-Type: multipart/form-data | Upload |
Authorization: Bearer <jwt> | Auth |
Accept-Language: fr | Langue |
X-Request-ID | Trace (optionnel, généré si absent) |
If-None-Match, ETag | Cache HTTP (réponses longues) |
