Aller au contenu

GraphQL et REST API

Copy of sumaris-pod/.agents/rules/graphql-rest-api.md (rule written for AI coding agents, when creating or modifying GraphQL services, REST controllers, FilterVO, FetchOptions, or JSON serialization). Do not edit here: run npm run site:sync-rules to update it.

GraphQL

  • Annotations : Toujours utiliser @GraphQLApi, @GraphQLQuery, @GraphQLMutation et @GraphQLArgument. Expose les mêmes méthodes avec:
    • Lecture: @GraphQLQuery(name=..., description=...) + @Transactional(readOnly = true).
    • Écriture: @GraphQLMutation(name=..., description=...) + @Transactional.
    • Chaque paramètre: @GraphQLArgument(name = "...").
  • Services : Le GraphQLService doit déléguer ses appels au Service correspondant (ex: PersonService).
  • Filtrage : Utiliser systématiquement les classes FilterVO (ex: PersonFilterVO) et FetchOptions pour les requêtes de liste.
  • Transactions : Utiliser @Transactional(readOnly = true) pour les queries et @Transactional pour les mutations.

REST

  • Beans POJO : Utiliser des classes dédiées pour le JSON (avec Lombok @Data, @Builder).
  • Nomenclature JSON : Utiliser @JsonProperty pour assurer le snake_case dans le JSON si nécessaire (ex: home_page_url).
  • Authentification : Utiliser AuthService.isLogin() et AuthService.hasUserProfile() pour sécuriser les endpoints.
  • Paths : Utiliser les constantes de RestPaths si elles existent.

  • Media Types : Spécifier explicitement produces et consumes (ex: MediaType.APPLICATION_JSON_VALUE).

  • Sérialisation JSON

    • Utilise des POJO dédiés (pas de Map) avec Lombok @Data, @Builder, @NoArgsConstructor, @AllArgsConstructor.
    • @JsonInclude(JsonInclude.Include.NON_NULL) et @JsonProperty si le champ diffère de la convention Java.
    • Regroupe les modèles par domaine (ex: paquetage feed).

  • Authentification/Autorisations via AuthService

    • authService.isLogin(), authService.hasUserProfile(UserProfileEnum), authService.getUserProfiles().
    • Filtre le contenu selon l'état d'authentification et les profils.

  • Endpoints

    • Méthodes HTTP adaptées, paths clairs et constants centralisés (classe RestPaths).
    • Déclare produces/consumes explicitement; documente l'endpoint.

  • Données et références utilisateur

    • Utilise SystemRecipientEnum (pas de chaînes en dur) et CryptoUtils.minifyPubkey().
    • Résout les personnes via PersonService et Persons.getDisplayName().
    • Internationalise tout message utilisateur (voir règle i18n).

Filtres et FetchOptions

  • Un FilterVO doit implémenter IDataFilter.
  • Un FetchOptions doit implémenter IFetchOptions.
  • Ces objets permettent de contrôler finement les données retournées et d'optimiser les performances.