Skip to content

Documentation de l'API REST

Vue d'ensemble

L'API suit les principes REST et utilise le format JSON pour les échanges de données. Tous les endpoints sont préfixés par /api/v1.

Schéma de Navigation

graph TD
    A["API Root"] --> B["/persons"]
    B --> C["GET /{personId}"]
    B --> D["POST /"]
    B --> E["PUT /{personId}"]
    B --> F["DELETE /{personId}"]
    B --> G["GET /"]

    B --> H["/persons/{personId}/favorites"]
    H --> I["POST /"]
    H --> J["DELETE /{favoriteId}"]
    H --> K["GET /"]

    B --> L["/persons/{personId}/attachments"]
    L --> M["POST /"]
    L --> N["DELETE /{entityId}"]
    L --> O["GET /"]

Endpoints Détaillés

Gestion des Personnes

GET /api/v1/persons/{personId}

Récupère les détails d'une personne.

Réponse : PersonRepresentation 

{
    "id": "uuid",
    "picture": "url",
    "lastName": "string",
    "firstName": "string",
    "gender": "MALE|FEMALE",
    "dateOfBirth": "date",
    "email": "string",
    "phoneNumber": {
        "indicative": "string",
        "number": "string"
    },
    "address": {
        "number": "string",
        "route": "string",
        "complement": "string",
        "stage": "string",
        "zipPostal": "string",
        "city": "string",
        "country": "string"
    },
    "type": "PRO|PART",
    "status": "ACTIVATED|ACTIVATION_IN_PROGRESS|MISSING_INFORMATIONS"
}

POST /api/v1/persons

Crée une nouvelle personne.

Corps de la requête : Person Réponse : PersonRepresentation

PUT /api/v1/persons/{personId}

Met à jour une personne existante.

Corps de la requête : Person Réponse : PersonRepresentation

DELETE /api/v1/persons/{personId}

Supprime une personne (suppression logique).

GET /api/v1/persons

Liste les personnes avec pagination et filtres.

Paramètres de requête : - currentPage : (Integer, min=0) - sizePage : (Integer, min=10) - personIds : (List, optionnel) - attachmentIds : (List, optionnel)

Réponse : ListPersonResume 

{
    "content": [PersonRepresentation],
    "currentPage": 0,
    "totalPages": 1,
    "totalElements": 10
}

Gestion des Favoris

POST /api/v1/persons/{personId}/favorites

Ajoute un favori à une personne.

Corps de la requête : Favorite 

{
    "entityType": "enum",
    "entityId": "string"
}
Réponse : FavoriteRepresentation

DELETE /api/v1/persons/{personId}/favorites/{favoriteId}

Supprime un favori.

GET /api/v1/persons/{personId}/favorites

Liste les favoris d'une personne.

Paramètres de requête : - entityType : (EntityTypeFavoris, requis) - currentPage : (Integer, min=1) - sizePage : (Integer, min=3)

Réponse : ListFavoriteResume

Gestion des Pièces Jointes

POST /api/v1/persons/{personId}/attachments

Ajoute une pièce jointe à une personne.

Corps de la requête : Attachment 

{
    "entityType": "ESTABLISHMENT|ORGANIZATION",
    "entityId": "string"
}
Réponse : AttachmentRepresentation

DELETE /api/v1/persons/{personId}/attachments/{entityId}

Supprime une pièce jointe.

GET /api/v1/persons/{personId}/attachments

Liste les pièces jointes d'une personne.

Paramètres de requête : - currentPage : (Integer, min=1) - sizePage : (Integer, min=3)

Réponse : ListAttachmentResume

Gestion des Erreurs

L'API utilise les codes HTTP standards et retourne des réponses d'erreur structurées :

{
    "message": "Description de l'erreur",
    "code": "CODE_ERREUR",
    "timestamp": "2025-04-27T12:34:56Z"
}

Codes d'erreur communs

  • 400 Bad Request : Requête invalide
  • 404 Not Found : Ressource non trouvée
  • 403 Forbidden : Action non autorisée
  • 500 Internal Server Error : Erreur serveur

Pagination

Toutes les listes sont paginées avec les paramètres suivants : - currentPage : Numéro de la page (commence à 0) - sizePage : Nombre d'éléments par page - La réponse inclut totalPages et totalElements