openapi: 3.0.3 info: title: API GraphQL Vocabulaires Verisav description: | API GraphQL permettant d'interroger les vocabulaires RDF/OWL Verisav (DPP, RMA, WTY) en temps réel. Cette API permet de récupérer les métadonnées, classes et propriétés des vocabulaires standardisés pour : - **DPP** : Passeports Produit Numérique (Digital Product Passport) - **RMA** : Autorisations de Retour de Marchandise (Return Merchandise Authorization) - **WTY** : Garanties et Contrats (Warranty & Contracts) Les vocabulaires sont alignés avec les standards GS1 Digital Link et la réglementation européenne ESPR (EU 2024/1781). ## Documentation complète - Documentation technique : https://www.verisav.fr/vocabularies/GRAPHQL_API.md - Page des vocabulaires : https://www.verisav.fr/vocabularies ## Exemples de requêtes GraphQL ### Lister tous les vocabulaires ```graphql query { vocabularies { id name namespace version title(lang: "fr") description(lang: "fr") } } ``` ### Récupérer un vocabulaire spécifique ```graphql query { vocabulary(id: "dpp") { id name namespace version classes { name label(lang: "fr") } properties { name type domain range } } } ``` version: 1.0.0 contact: name: Verisav url: https://www.verisav.fr email: contact@verisav.fr license: name: CC-BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ termsOfService: https://www.verisav.fr/cgu servers: - url: https://www.verisav.fr/api description: Serveur de production - url: http://localhost:3000/api description: Serveur de développement (local) tags: - name: GraphQL description: Endpoint GraphQL pour interroger les vocabulaires RDF/OWL paths: /graphql: post: tags: - GraphQL summary: Exécuter une requête GraphQL description: | Endpoint GraphQL permettant d'interroger les vocabulaires RDF/OWL Verisav. L'API supporte l'introspection GraphQL standard. Vous pouvez utiliser GraphiQL ou un outil comme GraphQL Playground pour explorer le schéma. ## Vocabulaires disponibles - **dpp** : Digital Product Passport Vocabulary - **rma** : Return Merchandise Authorization Vocabulary - **wty** : Warranty & Contracts Vocabulary ## Exemple de requête ```json { "query": "query { vocabularies { id name version } }" } ``` operationId: graphqlQuery requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: Requête GraphQL à exécuter example: "query { vocabularies { id name version } }" variables: type: object description: Variables pour la requête GraphQL additionalProperties: true operationName: type: string description: Nom de l'opération (pour les requêtes nommées) examples: listVocabularies: summary: Lister tous les vocabulaires value: query: | query { vocabularies { id name namespace version title(lang: "fr") description(lang: "fr") } } getVocabulary: summary: Récupérer un vocabulaire spécifique value: query: | query { vocabulary(id: "dpp") { id name namespace version classes { name label(lang: "fr") } properties { name type domain range } } } getClasses: summary: Lister les classes d'un vocabulaire value: query: | query { classes(vocabularyId: "dpp") { name label(lang: "fr") comment(lang: "fr") subClassOf status } } responses: '200': description: Réponse GraphQL réussie content: application/json: schema: type: object properties: data: type: object description: Données retournées par la requête GraphQL additionalProperties: true errors: type: array description: Erreurs éventuelles items: type: object properties: message: type: string locations: type: array items: type: object path: type: array items: type: string examples: vocabularies: summary: Liste des vocabulaires value: data: vocabularies: - id: "dpp" name: "dpp" namespace: "https://ns.verisav.fr/dpp#" version: "1.0.0" - id: "rma" name: "rma" namespace: "https://ns.verisav.fr/rma#" version: "1.0.0" - id: "wty" name: "wty" namespace: "https://ns.verisav.fr/wty#" version: "1.0.0" '400': description: Requête invalide content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string '500': description: Erreur serveur content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string get: tags: - GraphQL summary: Accéder à GraphiQL (si activé) description: | Interface GraphiQL pour explorer et tester l'API GraphQL interactivement. Disponible uniquement si `ENABLE_GRAPHIQL=true` en production. operationId: graphiql responses: '200': description: Interface GraphiQL content: text/html: schema: type: string '404': description: GraphiQL non disponible options: tags: - GraphQL summary: Options CORS description: Endpoint pour les requêtes CORS preflight operationId: graphqlOptions responses: '200': description: Options CORS headers: Access-Control-Allow-Origin: schema: type: string example: "*" Access-Control-Allow-Methods: schema: type: string example: "GET, POST, OPTIONS" Access-Control-Allow-Headers: schema: type: string example: "Content-Type, Authorization, Accept" components: schemas: Vocabulary: type: object description: Vocabulaire RDF/OWL Verisav properties: id: type: string description: Identifiant du vocabulaire (dpp, rma, wty) example: "dpp" name: type: string description: Nom du vocabulaire example: "dpp" namespace: type: string format: uri description: Namespace URI du vocabulaire example: "https://ns.verisav.fr/dpp#" prefix: type: string description: Préfixe recommandé example: "dpp" version: type: string description: Version du vocabulaire example: "1.0.0" title: type: string description: Titre du vocabulaire description: type: string description: Description du vocabulaire created: type: string format: date-time description: Date de création modified: type: string format: date-time description: Date de dernière modification creator: $ref: '#/components/schemas/Creator' publisher: type: string description: Éditeur du vocabulaire license: type: string format: uri description: Licence du vocabulaire example: "https://creativecommons.org/licenses/by/4.0/" classes: type: array items: $ref: '#/components/schemas/Class' description: Liste des classes du vocabulaire properties: type: array items: $ref: '#/components/schemas/Property' description: Liste des propriétés du vocabulaire Creator: type: object description: Créateur du vocabulaire properties: type: type: string description: Type du créateur (Person, Organization) example: "Person" name: type: string description: Nom du créateur seeAlso: type: array items: type: string format: uri description: Liens vers des profils du créateur Class: type: object description: Classe OWL définie dans le vocabulaire properties: name: type: string description: Nom de la classe example: "ProductPassport" label: type: string description: Label de la classe comment: type: string description: Description de la classe subClassOf: type: array items: type: string description: Classes parentes status: type: string description: Statut du terme (stable, unstable, deprecated) enum: [stable, unstable, deprecated] Property: type: object description: Propriété OWL définie dans le vocabulaire properties: name: type: string description: Nom de la propriété example: "hasWarranty" label: type: string description: Label de la propriété comment: type: string description: Description de la propriété type: type: string description: Type de propriété enum: [OBJECT_PROPERTY, DATATYPE_PROPERTY] domain: type: array items: type: string description: Domaines de la propriété range: type: array items: type: string description: Ranges de la propriété status: type: string description: Statut du terme (stable, unstable, deprecated) enum: [stable, unstable, deprecated]