API et intégrations accessibles

Vue d'ensemble

L'accessibilité des API (Application Programming Interface) garantit que les services web et les intégrations sont utilisables par tous, y compris par les développeurs en situation de handicap et par les applications d'assistance technologique.

Dans Codexia, l'API REST expose des données et des fonctionnalités de manière structurée et documentée. Ce document définit les standards d'accessibilité pour l'API et ses intégrations.

Principes d'accessibilité API

1. Documentation accessible

Documentation complète et claire

• Format HTML accessible (conformité WCAG 2.1 AA)
• Exemples de code avec commentaires
• Descriptions textuelles des endpoints, paramètres, réponses
• Diagrammes avec alternatives textuelles

Documentation interactive

• Interface accessible au clavier
• Contrastes conformes
• Support des lecteurs d'écran
• Exemples exécutables avec feedback accessible

Formats multiples

• Documentation HTML (prioritaire)
• OpenAPI/Swagger (description machine-readable)
• EPUB pour lecture hors-ligne (voir accessibility/epub.md)
• Exemples Postman/Insomnia

2. Réponses structurées et prévisibles

Format JSON standardisé

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "Introduction à l'accessibilité",
    "content": "...",
    "created_at": "2026-02-20T10:00:00Z"
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-20T10:30:00Z"
  }
}

Gestion des erreurs cohérente

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Les données fournies sont invalides.",
    "details": [
      {
        "field": "email",
        "message": "L'adresse email est obligatoire.",
        "type": "required"
      },
      {
        "field": "password",
        "message": "Le mot de passe doit contenir au moins 8 caractères.",
        "type": "min_length"
      }
    ]
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-20T10:30:00Z"
  }
}

Exigences :

• Messages d'erreur clairs et actionnables
• Codes d'erreur standardisés (HTTP + codes métier)
• Descriptions textuelles complètes
• Guidance pour résoudre l'erreur

3. Métadonnées riches

Descriptions sémantiques

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "Guide RGAA 4.1",
    "description": "Guide complet pour la conformité RGAA 4.1 niveau AA",
    "content_type": "documentation",
    "language": "fr",
    "accessibility_features": [
      "structuralNavigation",
      "tableOfContents",
      "alternativeText"
    ],
    "accessibility_hazards": ["none"],
    "accessibility_summary": "Contenu conforme WCAG 2.1 niveau AA"
  }
}

Métadonnées d'accessibilité (basées sur schema.org) :

• accessMode : Mode d'accès au contenu (textual, visual, auditory)
• accessModeSufficient : Modes d'accès suffisants
• accessibilityFeature : Fonctionnalités d'accessibilité
• accessibilityHazard : Dangers potentiels (flashing, sound, motion)
• accessibilitySummary : Résumé textuel de l'accessibilité

Endpoints Codexia

Structure d'URL RESTful

GET    /api/v1/documents           # Liste des documents
GET    /api/v1/documents/{id}      # Détail d'un document
POST   /api/v1/documents           # Créer un document
PUT    /api/v1/documents/{id}      # Modifier un document
DELETE /api/v1/documents/{id}      # Supprimer un document

Exigences :

• URL lisibles et prédictibles
• Versioning explicite (/v1)
• Noms au pluriel pour les collections
• Verbes HTTP standards (GET, POST, PUT, DELETE)

Exemple : GET /api/v1/documents

Requête :

GET /api/v1/documents?page=1&per_page=10&sort=created_at&order=desc HTTP/1.1
Host: api.codexia.dev
Accept: application/json
Authorization: Bearer {token}

Réponse :

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Guide d'accessibilité RGAA",
      "slug": "guide-accessibilite-rgaa",
      "description": "Guide complet pour la conformité RGAA 4.1",
      "content_type": "documentation",
      "language": "fr",
      "format": "markdown",
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-20T10:30:00Z",
      "accessibility": {
        "conformance_level": "AA",
        "wcag_version": "2.1",
        "features": ["structuralNavigation", "tableOfContents"]
      },
      "links": {
        "self": "/api/v1/documents/1",
        "html": "/guide-accessibilite-rgaa",
        "download": {
          "pdf": "/downloads/guide-accessibilite-rgaa.pdf",
          "epub": "/downloads/guide-accessibilite-rgaa.epub"
        }
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_items": 42,
    "total_pages": 5,
    "links": {
      "first": "/api/v1/documents?page=1&per_page=10",
      "prev": null,
      "next": "/api/v1/documents?page=2&per_page=10",
      "last": "/api/v1/documents?page=5&per_page=10"
    }
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-20T10:30:00Z"
  }
}

Exemple : POST /api/v1/documents

Requête :

POST /api/v1/documents HTTP/1.1
Host: api.codexia.dev
Content-Type: application/json
Authorization: Bearer {token}

{
  "title": "Nouveau guide",
  "description": "Description du guide",
  "content": "# Titre\n\nContenu en markdown...",
  "language": "fr",
  "format": "markdown"
}

Réponse (201 Created) :

{
  "status": "success",
  "data": {
    "id": 43,
    "title": "Nouveau guide",
    "slug": "nouveau-guide",
    "description": "Description du guide",
    "content_type": "documentation",
    "language": "fr",
    "format": "markdown",
    "created_at": "2026-02-20T11:00:00Z",
    "updated_at": "2026-02-20T11:00:00Z",
    "links": {
      "self": "/api/v1/documents/43",
      "html": "/nouveau-guide"
    }
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-20T11:00:00Z"
  }
}

Réponse (400 Bad Request - Erreur de validation) :

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Les données fournies sont invalides.",
    "details": [
      {
        "field": "title",
        "message": "Le titre est obligatoire et doit contenir entre 3 et 200 caractères.",
        "type": "required",
        "constraints": {
          "min_length": 3,
          "max_length": 200
        }
      }
    ]
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-20T11:00:00Z"
  }
}

Codes de statut HTTP

Utilisation cohérente et sémantique des codes HTTP :

Pagination accessible

Pagination par page

GET /api/v1/documents?page=2&per_page=20

Réponse avec métadonnées de pagination :

{
  "pagination": {
    "current_page": 2,
    "per_page": 20,
    "total_items": 150,
    "total_pages": 8,
    "links": {
      "first": "/api/v1/documents?page=1&per_page=20",
      "prev": "/api/v1/documents?page=1&per_page=20",
      "next": "/api/v1/documents?page=3&per_page=20",
      "last": "/api/v1/documents?page=8&per_page=20"
    }
  }
}

Liens HATEOAS (Hypermedia As The Engine Of Application State) :

• Fournir des liens vers les pages précédente/suivante
• Facilite la navigation programmatique
• Améliore la découvrabilité de l'API

Filtrage et tri

Filtrage

GET /api/v1/documents?language=fr&format=markdown&accessibility_level=AA

Tri

GET /api/v1/documents?sort=created_at&order=desc

Recherche

GET /api/v1/documents?search=accessibilité&fields=title,description,content

Exigences :

• Paramètres nommés de manière claire et cohérente
• Validation des paramètres
• Messages d'erreur explicites en cas de paramètre invalide

Authentification et sécurité

OAuth 2.0 / JWT

POST /api/v1/auth/token HTTP/1.1
Host: api.codexia.dev
Content-Type: application/json

{
  "grant_type": "password",
  "username": "user@codexia.dev",
  "password": "***"
}

Réponse :

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "def50200..."
  }
}

Rate limiting

Headers de réponse :

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1645363200

Réponse en cas de dépassement (429 Too Many Requests) :

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Vous avez dépassé la limite de requêtes autorisées. Veuillez réessayer dans 15 minutes.",
    "retry_after": 900
  }
}

Documentation API accessible

OpenAPI (Swagger)

Exemple de spécification OpenAPI 3.0 :

openapi: 3.0.0
info:
  title: Codexia API
  description: |
    API REST pour l'application Codexia.

    Cette API permet de gérer des documents, des utilisateurs et des métadonnées
    d'accessibilité. Tous les endpoints retournent des données au format JSON.
  version: 1.0.0
  contact:
    name: Support Codexia
    email: support@codexia.dev
    url: https://codexia.dev/support

servers:
  - url: https://api.codexia.dev/v1
    description: Production
  - url: https://api-staging.codexia.dev/v1
    description: Staging

paths:
  /documents:
    get:
      summary: Liste des documents
      description: |
        Retourne une liste paginée de documents avec leurs métadonnées
        d'accessibilité.
      parameters:
        - name: page
          in: query
          description: Numéro de page (commence à 1)
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: Nombre d'éléments par page
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Liste des documents récupérée avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '400':
          description: Paramètres de requête invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "Guide RGAA 4.1"
        description:
          type: string
          example: "Guide complet pour la conformité RGAA 4.1"
        language:
          type: string
          example: "fr"
        accessibility:
          $ref: '#/components/schemas/Accessibility'

    Accessibility:
      type: object
      description: Métadonnées d'accessibilité du document
      properties:
        conformance_level:
          type: string
          enum: [A, AA, AAA]
          example: "AA"
        wcag_version:
          type: string
          example: "2.1"
        features:
          type: array
          items:
            type: string
          example: ["structuralNavigation", "tableOfContents"]

Interface de documentation (Swagger UI)

Exigences d'accessibilité pour l'interface :

• Navigation clavier complète
• Support des lecteurs d'écran
• Contrastes conformes WCAG AA
• Formulaires de test accessibles
• Messages d'erreur clairs
• Code de réponse avec coloration syntaxique accessible

Webhooks et événements

Notification d'événement accessible :

POST https://client.codexia.dev/webhooks/codexia HTTP/1.1
Content-Type: application/json
X-Codexia-Event: document.created
X-Codexia-Signature: sha256=...

{
  "event": "document.created",
  "timestamp": "2026-02-20T11:00:00Z",
  "data": {
    "id": 43,
    "title": "Nouveau guide",
    "created_at": "2026-02-20T11:00:00Z",
    "accessibility": {
      "conformance_level": "AA",
      "wcag_version": "2.1"
    }
  }
}

Exigences :

• Type d'événement clair dans les headers et le body
• Données complètes pour éviter les requêtes supplémentaires
• Signature pour vérifier l'authenticité
• Retry avec backoff exponentiel en cas d'échec

Intégrations tierces

Clients SDK

Exigences pour les SDK (JavaScript, PHP, Python) :

• Documentation accessible
• Exemples de code commentés
• Gestion d'erreur robuste avec messages clairs
• Support TypeScript (typage fort)
• Tests automatisés incluant l'accessibilité

Exemple SDK JavaScript :

import { CodexiaClient } from '@codexia/sdk';

const client = new CodexiaClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.codexia.dev/v1'
});

// Gestion d'erreur accessible
try {
  const documents = await client.documents.list({
    page: 1,
    perPage: 10,
    language: 'fr'
  });

  console.log(`${documents.pagination.total_items} documents trouvés`);
} catch (error) {
  // Erreur structurée avec message clair
  console.error(`Erreur ${error.code}: ${error.message}`);

  // Détails de validation si disponibles
  if (error.details) {
    error.details.forEach(detail => {
      console.error(`- ${detail.field}: ${detail.message}`);
    });
  }
}

GraphQL (alternative REST)

Schéma accessible :

type Document {
  id: ID!
  title: String!
  description: String
  content: String!
  language: String!
  accessibility: Accessibility!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Accessibility {
  conformanceLevel: ConformanceLevel!
  wcagVersion: String!
  features: [String!]!
  hazards: [String!]!
  summary: String
}

enum ConformanceLevel {
  A
  AA
  AAA
}

type Query {
  """
  Liste des documents avec pagination et filtres
  """
  documents(
    "Numéro de page (commence à 1)"
    page: Int = 1

    "Nombre d'éléments par page"
    perPage: Int = 10

    "Filtrer par langue (code ISO 639-1)"
    language: String

    "Filtrer par niveau de conformité"
    accessibilityLevel: ConformanceLevel
  ): DocumentConnection!
}

Checklist API accessible

• Documentation accessible (HTML conforme WCAG AA)
• OpenAPI/Swagger avec descriptions complètes
• Interface de documentation accessible (Swagger UI)
• Réponses JSON structurées et prévisibles
• Messages d'erreur clairs et actionnables
• Codes HTTP utilisés correctement
• Métadonnées d'accessibilité dans les réponses
• Pagination avec liens HATEOAS
• Filtrage et tri avec paramètres clairs
• Rate limiting avec headers explicites
• Authentification sécurisée (OAuth 2.0/JWT)
• Webhooks avec événements structurés
• SDK avec gestion d'erreur robuste
• Exemples de code commentés et accessibles
• Tests automatisés incluant l'accessibilité
• Versioning explicite de l'API

Outils de validation

Tests automatisés

• Dredd : Tests basés sur la spec OpenAPI
• Postman : Tests d'API avec collections
• Newman : Runner CLI pour Postman

Documentation

• Swagger UI : Interface de documentation
• ReDoc : Documentation OpenAPI accessible
• Stoplight : Design et documentation d'API

Validation OpenAPI

• Spectral : Linter OpenAPI
• OpenAPI Validator : Validation de spec

Ressources

Standards

• OpenAPI Specification 3.0
• JSON:API : Spécification pour API JSON
• HAL (Hypertext Application Language)
• RFC 7807 - Problem Details for HTTP APIs

Guides

• Best Practices for REST API Design
• Microsoft REST API Guidelines
• Google API Design Guide

Accessibilité API

• W3C Web Accessibility and APIs
• Schema.org Accessibility Properties