openapi: 3.0.3
info:
  title: API SPARQL Vocabulaires Verisav
  description: |
    Endpoint SPARQL public pour interroger les vocabulaires RDF/OWL Verisav (DPP, RMA, WTY) en lecture seule.
    Les trois vocabulaires sont fusionnés en un seul graphe. Requêtes GET ou POST ; réponses en JSON ou XML.
    Documentation technique : https://www.verisav.fr/vocabularies/SPARQL_API.md
  version: 1.0.0
  contact:
    name: Verisav
    url: https://www.verisav.fr/support
    email: contact@verisav.fr
  license:
    name: CC-BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://www.verisav.fr/api
    description: Production
  - url: http://localhost:3000/api
    description: Développement local

paths:
  /sparql:
    get:
      summary: Exécuter une requête SPARQL (GET)
      description: |
        Envoie la requête SPARQL via le paramètre `query` (URL-encodé).
        Exemple : `?query=SELECT%20%3Fs%20%3Fp%20%3Fo%20WHERE%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D%20LIMIT%2010`
      operationId: sparqlGet
      parameters:
        - name: query
          in: query
          required: true
          description: Requête SPARQL (SELECT, ASK, CONSTRUCT, DESCRIBE)
          schema:
            type: string
            maxLength: 10000
        - name: format
          in: query
          required: false
          description: Format de réponse (défaut application/sparql-results+json)
          schema:
            type: string
            enum:
              - application/sparql-results+json
              - application/sparql-results+xml
            default: application/sparql-results+json
      responses:
        '200':
          description: Résultats SPARQL
          content:
            application/sparql-results+json:
              schema:
                type: object
                properties:
                  head:
                    type: object
                    properties:
                      vars:
                        type: array
                        items:
                          type: string
                  results:
                    type: object
                    properties:
                      bindings:
                        type: array
            application/sparql-results+xml:
              schema:
                type: string
                description: Résultats au format XML SPARQL
        '400':
          description: Requête invalide ou erreur d'exécution
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
    post:
      summary: Exécuter une requête SPARQL (POST)
      description: |
        Corps en `application/x-www-form-urlencoded` avec le champ `query`,
        ou en `application/sparql-query` avec le corps = requête SPARQL brute.
      operationId: sparqlPost
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  maxLength: 10000
                  description: Requête SPARQL
          application/sparql-query:
            schema:
              type: string
              description: Requête SPARQL en corps brut
      responses:
        '200':
          description: Résultats SPARQL
          content:
            application/sparql-results+json:
              schema:
                type: object
            application/sparql-results+xml:
              schema:
                type: string
        '400':
          description: Requête invalide
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string

tags:
  - name: SPARQL
    description: Endpoint SPARQL 1.1 pour les vocabulaires Verisav (DPP, RMA, WTY)